laravel/framework · error · ManagedQueueNotFoundException

Managed queue [{$name}] does not exist.

Error message

Managed queue [{$name}] does not exist.

What it means

Thrown as ManagedQueueNotFoundException (via QueueConnector::registerErrorHandling SQS-handler middleware) when an AWS SDK call returns error code AWS.SimpleQueueService.NonExistentQueue for a queue URL normalized through the Cloud Queue. The connector maps SQS's 'queue does not exist' error into a friendlier domain exception naming the managed queue. Fires on any SQS operation against an unprovisioned/renamed queue (send, receive, delete, change visibility).

Source

Thrown at src/Illuminate/Foundation/Cloud/QueueConnector.php:77

        $this->configureWorker($queue);
        $this->configureFailedJobProvider($queue);

        return $queue;
    }

    /**
     * Register SQS client middleware that translates "queue does not exist" errors into ManagedQueueNotFoundExceptions.
     */
    protected function registerErrorHandling(SqsClient $sqs, Queue $queue): void
    {
        $sqs->getHandlerList()->appendSign(function (callable $handler) use ($queue) {
            return function (CommandInterface $command, RequestInterface $request) use ($handler, $queue) {
                return $handler($command, $request)->otherwise(function ($reason) use ($command, $queue) {
                    if ($reason instanceof AwsException &&
                        $reason->getAwsErrorCode() === 'AWS.SimpleQueueService.NonExistentQueue') {
                        $name = $queue->normalizeQueue($command['QueueUrl'] ?? null);

                        throw new ManagedQueueNotFoundException(
                            "Managed queue [{$name}] does not exist.", 0, $reason,
                        );
                    }

                    throw $reason;
                });
            };
        }, 'managed-queue-not-found');
    }

    /**
     * Configure the queue.
     */
    protected function configureQueue(Queue $queue): void
    {
        $this->app['events']->listen(fn (JobQueued $event) => $event->connectionName === $queue->getConnectionName()
            ? $queue->finishQueueingJob($event->queue)
            : null);

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Verify the queue name in config/queue.php (connections.cloud.queue or the per-job onQueue()) matches a provisioned Cloud-managed queue.
2. Provision the missing queue through the Cloud console / CLI.
3. Confirm you are targeting the correct environment (staging vs production queue sets).
4. Catch ManagedQueueNotFoundException and alert ops / fail the dispatch gracefully.

Example fix

// before
SomeJob::dispatch($payload)->onQueue('emails');
// throws ManagedQueueNotFoundException if 'emails' is not provisioned

// after
use Illuminate\Foundation\Cloud\ManagedQueueNotFoundException;

try {
    SomeJob::dispatch($payload)->onQueue('emails');
} catch (ManagedQueueNotFoundException $e) {
    report($e);
    // fall back to a known-good queue or surface a clear ops alert
    SomeJob::dispatch($payload)->onQueue(config('queue.connections.cloud.queue'));
}

use Illuminate\Support\Facades\Storage;
use Aws\Sqs\SqsClient;

// Verify the queue exists before relying on it (optional, costs an API call):
$sqs = app(SqsClient::class);
$prefix = config('queue.connections.cloud.prefix');
$queueName = config('queue.connections.cloud.queue');
try {
    $sqs->getQueueUrl(['QueueName' => $queueName]);
} catch (\Aws\Exception\AwsException $e) {
    if ($e->getAwsErrorCode() === 'AWS.SimpleQueueService.NonExistentQueue') {
        throw new \RuntimeException("Managed queue [{$queueName}] is not provisioned.");
    }
    throw $e;
}

use Illuminate\Foundation\Cloud\ManagedQueueNotFoundException;

function isManagedQueueMissing(\Throwable $e): bool {
    return $e instanceof ManagedQueueNotFoundException;
}

use Illuminate\Foundation\Cloud\ManagedQueueNotFoundException;

try {
    SomeJob::dispatch($payload)->onQueue($queueName);
} catch (ManagedQueueNotFoundException $e) {
    // alert ops / fall back to a known-good queue
    report($e);
    SomeJob::dispatch($payload)->onQueue(config('queue.connections.cloud.queue'));
}

When it happens

Trigger: Dispatching a job (or a worker polling) on a cloud queue whose name resolves to an SQS QueueUrl that does not exist. Reached via dispatch(), the worker's receive loop, or any SQS client call wrapped by registerErrorHandling when the underlying queue was deleted/renamed/never provisioned.

Common situations: Queue name typo in config or job->onQueue(). Queue was deleted in the Cloud console or via infra-as-code teardown. Environment mismatch (production queue name used in staging where it isn't provisioned). Recent rename without updating config/queue.php connections.cloud.queue.

Related errors

• The failed job provider does not have a configured queue
• Queue resolver did not return a Queue implementation.
• To enable support for closure jobs, please install the illum
• The Laravel Cloud agent runtime socket is unreachable.
• The Laravel Cloud agent returned HTTP {$response->status()}

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/876cda228be1d98c.json. Report an issue: GitHub.