Skip to main content

Troubleshooting

Start with the first failing boundary: registration, query, conversion, storage, or delivery. Preserve the original exception because it contains the feed class and output context.

The feed class is not found​

Confirm that the registration contains the full class name, Composer autoloading can resolve it, and the class extends DragonCode\LaravelFeed\Feeds\Feed or a preset. Run composer dump-autoload after moving a class.

Generation uses too much memory​

  • Return an Eloquent Builder from builder().
  • Do not call get(), all(), or toArray() on the complete dataset.
  • Lower chunkSize() and measure again.
  • Split large outputs with perFile().
  • Move work to an asynchronous queue only after the feed itself remains streaming.

See performance.

A queue job never runs​

Check FEED_QUEUE_CONNECTION, FEED_QUEUE_NAME, and the worker command. The sync connection runs immediately and does not test asynchronous delivery. A uniqueness lock can suppress another job for the same feed until FEED_QUEUE_UNIQUE_TTL expires.

The storage disk is rejected​

The disk must resolve to Illuminate\Filesystem\FilesystemAdapter and support writable streams, moves, directory management, listings, and deletion. A custom implementation that is not a FilesystemAdapter fails before the database query with UnsupportedStorageDiskException. A Laravel read-only disk passes that type check. Its write fails during publication, after the feed query and local staging have completed, and GeneratorService wraps the storage failure in FeedGenerationException.

XML generation fails​

Validate raw XML passed through @mixed, ensure CDATA content is valid, and keep directive values within their documented scalar or array contracts. Prefer normal escaped values unless raw XML is required.

CSV rows fail after the first item​

CSV establishes its columns from the output schema. Every item must produce the same keys. Optional values keep an empty column rather than removing it.

Published files are incomplete or stale​

Inspect the original storage exception and verify disk permissions. On remote disks, account for eventual consistency and non-atomic copy-and-delete moves. Generators on multiple hosts need an external distributed lock when they can publish the same target.

During publication, Laravel Feeds creates a temporary .feeds_staging_* directory next to the target path. It removes this directory after a successful publication and after ordinary generation failures. The directory is preserved when rollback fails so that its backups remain available. An interrupted process or a cleanup failure can also leave one behind.

A large or growing number of .feeds_staging_* directories indicates repeated publication or cleanup failures. Inspect the generation logs and the original exception, fix the underlying storage, permission, or process failure, and review any preserved backups before deleting stale directories manually.

See Also​