ArtisanPack UI Docs

Solutions to common issues with ArtisanPack UI SEO. If you're migrating from another SEO package: If auto-discovery isn't working: 1. Check component is...

Solutions to common issues with ArtisanPack UI SEO.

Installation Issues

Migration fails with "table already exists"

If you're migrating from another SEO package:

# Check existing tables
php artisan tinker
>>> Schema::hasTable('seo_meta')

# If the table exists, either:
# 1. Drop and recreate (loses data)
php artisan migrate:fresh

# 2. Or skip specific migrations
# Add to migrations/seo tables to ignore list

Service provider not found

If auto-discovery isn't working:

// Add to config/app.php
'providers' => [
    ArtisanPackUI\Seo\SeoServiceProvider::class,
],

Composer dependency conflict

# Clear composer cache
composer clear-cache

# Update with verbose output
composer update artisanpack-ui/seo -vvv

Meta Tags Not Showing

Tags missing from page

Check component is in <head>:

<head>
    <x-seo-meta :model="$model" />
</head>

Verify model is passed to view:

return view('page', ['model' => $post]);

Check model has HasSeo trait:

class Post extends Model
{
    use HasSeo;
}

Fallback values not working

Ensure your model has the expected attributes:

// For title fallback, model needs one of:
$post->title
$post->name

// For description fallback:
$post->description
$post->excerpt
$post->content

Or override the methods:

protected function getSeoTitleAttribute(): ?string
{
    return $this->headline;
}

Title showing twice

Check you're not manually adding a <title> tag alongside the component:

{{-- Remove this if using component --}}
<title>{{ $title }}</title>

{{-- Component includes <title> tag --}}
<x-seo-meta :model="$model" />

Facebook not showing correct image

Verify image is accessible: Visit the URL directly
Check image size: Minimum 1200x630 pixels
Use absolute URL: https://example.com/image.jpg
Clear Facebook cache: Use Sharing Debugger

# Test image URL
curl -I https://example.com/your-image.jpg

Twitter Card not appearing

Validate card: Use Twitter Card Validator
Check card type is valid: summary, summary_large_image, app, player
Ensure all required tags are present

LinkedIn showing old data

LinkedIn caches aggressively. Use the Post Inspector to clear cache.

Redirect Issues

Redirects not triggering

Check middleware is registered:

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \ArtisanPackUI\Seo\Http\Middleware\HandleRedirects::class,
    ]);
})

Verify redirect is active:

$redirect = Redirect::where('source', '/old-path')->first();
dd($redirect->is_active); // Should be true

Check match type:

php artisan seo:test-redirect /your-path

Regex redirect not matching

Don't include delimiters: Use ^/path/(\d+)$ not /^\/path\/(\d+)$/
Escape special characters: / doesn't need escaping
Test pattern:

preg_match('/^\/path\/(\d+)$/', '/path/123', $matches);
dd($matches);

Redirect loop detected

The package prevents loops automatically. If you see this error:

Check for circular redirects
Verify chain depth doesn't exceed max_chain_depth (default: 5)
Review redirect targets

Sitemap Issues

Sitemap returns 404

Check routes are enabled:

// config/seo.php
'routes' => [
    'sitemap' => true,
],

Or add custom route:

Route::get('/sitemap.xml', [SitemapController::class, 'index']);

Sitemap is empty

Check providers are registered
Verify models are not excluded:

$post->shouldBeInSitemap(); // Should return true

Check for noindex:

$post->seoMeta->noindex; // Should be false
$post->seoMeta->exclude_from_sitemap; // Should be false

Sitemap URLs are wrong

Check APP_URL in .env:

APP_URL=https://example.com

Verify model URL generation:

$post->getSeoUrl();

Analysis Issues

Analysis not running

Check analysis is enabled:

// config/seo.php
'analysis' => [
    'enabled' => true,
],

Verify focus keyword is set:

$post->seoMeta->focus_keyword;

"Meta description is missing." on every record

If the model gets its seoMeta relation from Model::resolveRelationUsing() rather than the HasSeo trait, versions before 1.7.1 didn't detect the relation. Analysis ignored the saved meta description and focus keyword and never cached results. Upgrade to 1.7.1 or later.

Analysis queue not processing

# Check queue is running
php artisan queue:work

# Check failed jobs
php artisan queue:failed

Cache Issues

Changes not reflecting

# Clear SEO cache
php artisan seo:clear-cache

# Clear application cache
php artisan cache:clear

# Clear config cache
php artisan config:clear

Cache errors with Redis

# Check Redis connection
redis-cli ping

# Check Laravel can connect
php artisan tinker
>>> Cache::put('test', 'value', 60)
>>> Cache::get('test')

Livewire Component Issues

Component not loading

Check Livewire is installed:

composer show livewire/livewire

Verify scripts are included:

@livewireStyles
@livewireScripts

Save not working

Check browser console for errors
Verify CSRF token:

<meta name="csrf-token" content="{{ csrf_token() }}">

Check Livewire endpoint is accessible:

curl -X POST https://example.com/livewire/message/seo-meta-editor

Preview not updating

The preview updates on wire:model changes. Ensure you're using:

wire:model.live="field"

Database Issues

Column not found error

Run migrations:

php artisan migrate

If migrations are out of sync:

php artisan migrate:status

Data type mismatch

Check your model casts:

protected $casts = [
    'schema_data' => 'array',
    'secondary_keywords' => 'array',
    'hreflang' => 'array',
];

Performance Issues

Pages loading slowly

Enable caching:

'cache' => [
    'enabled' => true,
    'driver' => 'redis',
],

Warm cache after deployments:

php artisan seo:warm-cache

Reduce query calls:

// Eager load SEO meta
$posts = Post::with('seoMeta')->get();

Analysis taking too long

Queue analysis:

'analysis' => [
    'queue' => true,
],

Reduce analyzers:

'analyzers' => [
    'readability' => ['enabled' => false],
],

Error Messages

"Model must use the HasSeo trait or define a seoMeta relationship."

Add the trait to your model:

use ArtisanPackUI\Seo\Traits\HasSeo;

class Post extends Model
{
    use HasSeo;
}

If you can't edit the model, register the relation at runtime instead. See Models Without the Trait.

"Invalid schema type"

Check the schema type is supported:

// Supported types
Article, BlogPosting, Product, Event, Organization,
LocalBusiness, WebSite, WebPage, Service, Review,
AggregateRating, BreadcrumbList, FAQPage

"Redirect loop detected"

Review your redirects for circular references:

php artisan seo:test-redirect /path

Getting More Help

Enable Debug Mode

// config/seo.php
'debug' => true,

Check Logs

php artisan pail
# Or
tail -f storage/logs/laravel.log

Report Issues

If you've found a bug:

Search existing issues first
Include Laravel and package versions
Provide reproduction steps
Include relevant config and code

Report an Issue

Troubleshooting