Troubleshooting

A setting the feature needs is empty or invalid. The bundle checks when a feature is first used, not at boot. The message names the setting:

The SDK needs a PSR-18 client and PSR-17 factories. http_client isn't set, FrameworkBundle didn't register psr18.http_client (it needs symfony/http-client plus a PSR-17 implementation), and discovery found nothing else installed. A typo in http_client leads here too, because a missing service id falls back to discovery.

The bundle ships its routes but never loads them by itself. Without a route import, neither path exists. The default OAuth redirect URI is generated from adobe_sign_oauth_callback, so it fails if only the webhook routes are imported.

A configuration key names a service that doesn't exist: webhooks.messenger without Messenger installed (or a wrong bus), token_store: doctrine without DoctrineBundle (or a wrong doctrine.connection), a misspelt cache_pool or token_cache_pool, or a token_store / user_key_resolver id that isn't a service.

The Integration Key is wrong, truncated, revoked, or belongs to a user who was deactivated. Quotes or spaces copied into .env.local are a common cause.

When the callback runs, security.token_storage holds no user. Either the callback path isn't covered by a firewall that authenticates users (a security: false firewall, or a pattern that misses /adobe-sign/oauth), SecurityBundle isn't installed, or the user's session ended while they were at Adobe (expired, or a different host lost the cookie).

The state in the URL doesn't match the one in this session, or the session has none. Typical causes: the flow started on www.example.com and the redirect URI points at example.com (different cookie, different session); the session expired or wasn't persisted (a stateless firewall, a session handler that drops writes); the user started connecting in two tabs (the second overwrites the first state); or they refreshed or bookmarked the callback URL (the state is single-use).

The redirect URI the bundle sends doesn't match the one registered on the API application character for character. With redirect_uri: ~ it is generated from the current request: behind a TLS-terminating proxy without trusted_proxies it becomes http://…; on another host or port, or under a route prefix, it differs too.

The OAuth controller keeps the state in the session, and sessions are disabled (framework.session: false or not configured), as in API-only apps.

NO_TOKEN: nothing readable is stored under that key: the user never connected, the key changed (a new UserKeyResolver, a changed user identifier), the token was lost or can't be decrypted (see lost and unreadable tokens). The others: the refresh token no longer works, because the user or an admin revoked access or it went unused for too long.

With token_store: cache, tokens live in oauth.token_cache_pool, cache.app by default: a filesystem pool under var/cache on each machine. A new container, a deploy that replaces var/, cache:pool:clear, an array or APCu pool, a pool with a default_lifetime, or Redis evicting keys all lose them; separate servers never shared them.

Tokens are encrypted with a key derived from oauth.encryption_key, which defaults to %kernel.secret%. Values encrypted with another key decrypt to null by design, so the store reports "no token".

token_store: doctrine is set but the table was never created on that connection: no migration was generated, it wasn't run in this environment, a schema_filter hid it, or oauth.doctrine.connection points at a different database than the one you migrated.

The client id Adobe sends isn't in webhooks.client_ids (or oauth.client_id when the list is empty). Common reasons: webhooks created with an Integration Key carry a different application's id than you assumed; an explicit client_ids list replaced the OAuth client id; staging and production use different applications; or a proxy strips the header.

A firewall or an access_control rule requires a user for the webhook path: a catch-all such as { path: ^/, roles: ROLE_USER }, a rule for ^/adobe-sign meant for the OAuth routes, or a stateless API firewall that demands a token for every path.

The webhook route is stateless, but something started the session for it: usually a non-lazy stateful firewall covering the path, or one of your own listeners reading the session or the user on every request.

The URL starts with http://. With generateUrl(..., ABSOLUTE_URL) that means Symfony thinks the request was plain HTTP (a proxy without trusted_proxies), or you're in the console or a worker without framework.router.default_uri, so the router used http://localhost.

Duplicate detection lives in cache_pool. If each server has its own (cache.app on local disk), a retry that lands on another server looks new. It also happens after the pool was cleared, when dedupe_ttl is shorter than Adobe's 72-hour retry window, or when Messenger redelivers a message after a crash (deduplication can't help there).

Adobe disables a webhook after 72 hours of failed deliveries: an outage, an expired certificate, a deploy that put the path behind a login, a 403 after an allow-list change. Notifications while it is disabled are not sent later.

In order of likelihood: no worker is consuming the transport the message is routed to; webhooks.messenger isn't enabled in this environment (only WebhookReceivedEvent fires); the message went to another bus than the one your handler is registered on; the handler returned early (wrong event type, agreement not found); the message failed and sits in the failure transport; or it was a duplicate.

webhooks.messenger is on, the message isn't routed to a transport, and the bus has no handler for it, so Messenger refuses it inside the webhook request. The bundle doesn't record a notification it failed to handle, so Adobe keeps retrying, but it gives up after 72 hours.

The request went to the wrong data centre. The SDK already handles the normal case: on this error it forgets the cached data centre, rediscovers it and retries once. If you still see it, the rediscovery itself points somewhere the credentials don't belong: a wrong bootstrap_url (for example an account in a separate Adobe environment against the commercial host), or an OAuth token whose stored access point no longer matches the account.

The request is valid, but the Acrobat Sign account's plan or settings don't allow it: mixed sequential and parallel signing (hybrid routing), an identity method that isn't enabled or is out of quota, digital signatures not enabled for AES or QES, a sending limit.

Adobe processes new agreements asynchronously. The status is DOCUMENTS_NOT_YET_PROCESSED for a few seconds, and participant data lags behind the status.

Adobe throttled the account. The SDK retries 429 and 503 itself up to retries.max times, waiting up to retries.max_delay_seconds each; it throws when Adobe asks for a longer wait or the retries run out.