Troubleshooting.

Start with the active identifier and configured driver:

dump([
    'driver' => config('whitelabel.driver'),
    'resolved' => Whitelabel::isResolved(),
    'brand' => Whitelabel::current()?->id(),
]);

Then use the matching section below.

No brand resolves

Whitelabel::current() returns null. Every resolver returned null, or whitelabel.resolvers is empty or not an array. Restore DefaultResolver and confirm whitelabel.default names an available brand.

A console command or worker does not use a domain brand. DomainResolver requires a real HTTP request with a Host header. Outside HTTP, use explicit activation, BrandAware, a tenant, or the default.

A request uses the default instead of its domain. Define a bare host without a scheme or path, then clear retained state if you changed config after the first read:

Whitelabel::forget();

Domain matching is case-insensitive. Ports are not part of Laravel's Request::getHost() value.

Definition errors

Every package exception implements WhitelabelException. Catch that interface when one handler should cover package failures.

“sets […] to null.” Remove the key to inherit or use an empty string or list to clear it. Null is rejected at every nested depth.

“defines an unknown key.” Use only name, domain, logo, favicon, colors, mail, and settings at the top level. Application-specific keys belong under settings.

A domain is rejected. Store app.acme.com, not a URL such as https://app.acme.com/path.

A sender address is rejected. mail.from_address must be a valid email address or an empty string.

The configured default is unknown. With the config driver, define the identifier named by whitelabel.default. The check runs after all definitions are validated, so the package may report a malformed definition first.

Components render nothing

Logo and favicon components render nothing when their effective asset is absent or cleared. The styles component renders nothing when no valid non-empty colour variables remain. All three render nothing when no brand resolves.

The package does not check file existence. If a tag renders but the browser gets a 404, verify the disk, path, public visibility, and storage:link setup.

For favicons with unknown file extensions, pass type explicitly.

Mail is not branded

Confirm whitelabel.mail.markdown is not false. Application-published files under resources/views/vendor/mail override the package's Markdown components.

Sender replacement requires the exact boolean true at whitelabel.mail.override_from and a non-empty active-brand mail.from_address. Messages without an active brand keep Laravel's sender.

If the visual sender is correct but delivery fails, check provider authorization and SPF, DKIM, and DMARC. The package cannot verify those records.

A queued job has the wrong brand

Add BrandAware to the user job, mailable, notification, or listener class. The payload may carry an identifier for every job, but restoration only occurs for classes that opt in.

CapturedBrandMissing means the captured identifier was deleted before the worker started. Restore the brand and retry, or replace the job. The package refuses to fall back because that would run branded work under another identity.

For Spatie tenant-aware work, ensure SwitchTenantBrandTask is registered and the configured tenant model implements ProvidesBrand.

Brand data appears stale

Writes through BrandRepository invalidate the relevant cache automatically. If another process changed the database or custom data source directly, clear the package keys:

php artisan whitelabel:clear

With Spatie cache prefixes, confirm the configured Whitelabel cache store is also tenant-prefixed. Leave whitelabel.cache.store as null to use the store that Spatie prefixes.

In a long-running test or process after changing configuration, call Whitelabel::flush() and BrandRepository::flush() as appropriate. The test trait handles both active runtime definitions and resolution state between tests.

Repository writes fail

UnsupportedBrandOperation means the active driver is config, which is read-only. Switch to database or a writable custom driver.

BrandAlreadyExists means the identifier or non-null domain has a unique-key collision. Update the existing identifier or assign a domain that belongs to no other brand.

UnknownBrand from update() means no stored row matches the identifier. Use create() for a new brand.

What to read next

• Configuration to compare every key with its default.
• Public API for exception and method references.
• Testing to isolate brand state in an application test suite.