Skip to content
Scalpels home

Scalpels is officially launching on October 31, 2026. Special early adopter pricing is available now.

← All documentation

Documentation

Reel

Troubleshooting

Updated

The deploy fails at reel:smoke

reel:smoke runs after the migrations on every deploy and refuses to call Reel ready unless the database, the private bucket and the managed queue all work. A failure means a resource is missing or not attached, or an environment value is shadowing one that Laravel Cloud injects. Check in the Laravel Cloud dashboard that the cache, bucket and queue are attached to the environment, and remove any DB_*, AWS_*, SQS_*, FILESYSTEM_DISK, QUEUE_CONNECTION or CACHE_STORE values you added yourself. Then use Resume on the deployment in Scalpels (Install a product).

If you run it on your own machine, it fails with "The configured filesystem driver [local] is not S3-backed". That is expected: it only passes against real object storage and a real queue.

Every request fails with "CACHE_STORE must name a configured cache store."

Reel refuses to boot when its cache store is not configured, because its scheduled jobs use cache locks to avoid overlapping runs. Scalpels provisions a managed Laravel Valkey cache and Laravel Cloud injects its store selection. If the deployment shows this error, check that the cache is attached to the environment and remove any CACHE_STORE value you added yourself, then use Resume on the deployment in Scalpels.

Sessions stay in Recording, Closing or Compacting

Sessions are closed and compacted by the scheduler and the queue. reel:smoke does not prove the scheduler is running. Check in Laravel Cloud that the scheduler is enabled and that its runs appear. Then look at the Dashboard in Reel: Awaiting compaction, Queue lag seconds and Failed jobs show where work is stuck.

Remember that a session needs about 17 minutes after the last activity, plus compaction, before it is Ready. A session that cannot be compacted ends as Failed.

reel:install fails with "Reel rejected the enrollment request."

Most often the code expired: it lives 15 minutes. In Reel, open the application's Signing credentials:

  • If the credential reads Pending enrollment and is the first one, select Revoke, then Issue credential, and use the new code straight away.
  • If you were rotating, use Reissue pending code on the active credential.

The same message also covers a mistyped application ID, an unreachable Reel URL, and an application whose ingest is disabled. Check those if a fresh code does not help.

composer require artisan-build/reel-client cannot find the package

The client is not on Packagist. Copy it into your application and add it as a relative path repository, as shown in Connecting your apps. If your deploy fails with Source path "..." is not found for package artisan-build/reel-client, the path repository points at a folder on your own machine: use the relative vendor-src/reel-client path and commit that folder.

Composer also refuses the client on applications older than Laravel 13.

Nothing is recorded in a deployed application

Run curl -sI https://<your-app-hostname>/reel/assets/reel-recorder-0.1.0.js. A 404 means the client is switched off in that environment because REEL_URL and REEL_PRIVATE_KEY are not set there. reel:install only wrote them to your local .env.

If the client is on, check what Reel.start() returned. awaiting_consent, refused_gpc and hidden each explain why recording did not start; see Privacy and capture.

Sessions never appear in Reel

When uploads reach Reel but are rejected, Reel answers with a short reason. Look for it in the browser's network panel on the request to /api/chunks:

Reason What to fix
application_disabled Ingest is switched off for the application, or the application ID is wrong. Select Enable ingest.
origin_mismatch or invalid_grant The page's origin is not in Allowed origins (scheme and host must match exactly), or the key that signed the grant is not active in Reel.
daily_session_limit, concurrent_session_limit The application reached its 1,000 new sessions per day or 100 concurrent sessions.
request_too_large, compressed_chunk_too_large, decompressed_chunk_too_large A chunk exceeded Reel's size limits, usually from a very large page.
unmasked_form_value, blocked_media_element, unsafe_attribute and similar The server's privacy check found content the recorder should have removed. Reel does not store the rejected data. Make sure the client in your application is the same version as your Reel deployment.

A replay looks wrong or will not load

Missing images, fonts and styling are expected: playback never loads anything from the network. If the session page says Missing replay data detected, part of the recording could not be reconstructed. Completeness not confirmed only means the browser did not send a final closing upload, which happens when a tab is closed abruptly.

If the player reports that the replay is not ready, the session has not reached Ready yet.

Storage keeps growing

Protected recordings never expire. Review them with the Protection filter on Sessions. The Dashboard shows estimated storage, the last retention sweep and the oldest overdue expiry. If expiry is behind, check that the scheduler is running. Never add a bucket lifecycle rule; it would delete protected recordings too.