Troubleshooting

Every error from the Dekka API has a code, a message and a request_id, and the dashboard shows the message. The sections below are named after what you'll see.

My build failed

Open the deployment and choose Jump to first error. A deployment that fails with build_failed usually has a missing lockfile, a build command that only works on your machine, or the wrong Root directory in a monorepo. Set the build and start commands yourself or switch the builder to Dockerfile in build settings, and remember that a dekka.toml or dekka.json in the repository overrides the dashboard.

A deployment that fails with invalid_config before it builds has a problem in its config file, and the message names the setting. Config as code lists the usual causes.

My deploy is stuck on Starting or failed its health check

Dekka is waiting for the health check, and health_check_failed means it gave up. Check that your service:

• listens on 0.0.0.0 rather than localhost,
• listens on the port in its settings, which it also receives as PORT, and
• returns a 2xx on the health check path within the timeout, which is 30 seconds unless you changed it.

The release that was serving before keeps serving while you fix it.

"Some references do not match a service or variable in this environment"

This is 422 unknown_reference. A value contains ${{name.KEY}} where no service in the environment is called name, the service has no variable KEY, or the reference is malformed. The error's details.references lists each one with a reason of unknown_service, unknown_variable or malformed. References only reach services in the same environment, and shared variables are written ${{shared.KEY}}.

If a deploy or restart fails with unknown_reference, reference_cycle or reference_too_deep, a reference that used to work has broken, two values refer to each other, or references nest more than ten levels deep. The message names the chain.

My custom domain says "DNS doesn't match"

Dekka couldn't find the TXT record at _dekka-challenge.<your domain> with the value it showed you. Many DNS providers add your domain to the end of the name you type, so enter _dekka-challenge.shop rather than _dekka-challenge.shop.example.com for shop.example.com, and check the record with dig TXT _dekka-challenge.shop.example.com. New records can take a few minutes to appear, and you can choose Check DNS again once they do. If the domain is verified but doesn't load, its CNAME doesn't point at the service's apps.dekka.cloud address yet.

"entitlement_exceeded"

You've reached a limit of your plan, and the message says which one. Stopping or deleting a service frees an active-service slot, and Plans and limits lists every limit and how it's counted. To go further, change plan from Billing.

"spend_limit_reached"

This period's estimated usage charges have reached the organisation's hard spend limit, so Dekka refuses new services, deployments, scaling up and metered use until the next period starts. Services that are running keep running. An owner or admin can raise or remove the limit under Spending alerts and limit on the Billing page, and the error's details show the limit, the estimate and when the period ends. See Plans, billing and usage.

My invitation doesn't work

invitation_email_mismatch means you're signed in with a different address from the one the invitation was sent to, so sign out and sign in with that address. invalid_invitation means the link expired, which happens after seven days, was revoked or was already used, and whoever invited you can send a new one from Settings, then Organisation. See Organisations and members.

I can't sign in with GitHub

github_email_unverified means your GitHub account has no verified primary email address, so Dekka can't match it to an account or create one. Sign in with an email link, then connect GitHub from Settings, then Account, and GitHub sign-in works from then on.

github_unavailable means GitHub sign-in is turned off, so sign in with an email link, Google or a passkey. See Signing in.

My service can't reach its database

Check the line between them on the canvas. A dashed line means the connection is still being set up, and a red one means it failed, which you can select to retry. Then make sure your code reads DATABASE_URL or REDIS_URL rather than a hard-coded address. If connecting fails with env_key_conflict, the service already has a variable of its own with that name, so remove it and connect again.

My private image won't pull

image_pull_unauthorized means the registry turned the credential down, so check the token hasn't expired and can read the package. registry_credential_mismatch means the credential is for a different registry host from the image. See Registry credentials.

The AI Gateway refused my request

model_not_found means the model ID isn't in the catalogue or is no longer available, and GET /v1/ai/models lists the ones your key may use. model_not_allowed means the project's routing rules, or the AI Gateway node the service is connected to, don't allow that model. spend_cap_reached means the project has reached its monthly cap, which you can raise under AI Gateway, then Routing, or wait for the next calendar month. See Routing rules.

provider_unavailable means there is no key for the model's provider, so add your own under AI Gateway, then Keys. provider_auth_failed means the provider turned that key down, so check it hasn't been revoked at the provider and save it again. See AI keys.

endpoint_unavailable means you called a private/<name> model in production, and the endpoint is on the waitlist until GPU capacity exists. Outside production the same request gets a simulated reply. See GPU instances.

Other errors

Code	What to do
branch_not_found	The branch doesn't exist in the repository. Check its name in the service's settings.
confirmation_required	Deleting a database or a queue, or restoring a backup, needs its name as confirm.
resource_has_connections	Disconnect the services using a database, bucket or queue before deleting it.
kind_not_available	That kind of resource can't be created yet. GPU instances are on the waitlist.
volume_requires_single_replica	Set Replicas to 1 before adding a volume.
project_not_empty	Delete a project's services before deleting the project.
invalid_api_key	The API key is wrong, expired or revoked.
last_owner	An organisation needs at least one owner. Make someone else an owner before changing the role of the only owner or removing them.
already_member	The address you invited already belongs to a member of the organisation.
server_not_stopped	Stop a server before resizing it.
disk_shrink_not_supported	A server's disk only grows, so choose a size with at least as much disk.
ssh_key_too_weak	The RSA key has fewer than 2048 bits. Add an ed25519 key instead.
private_key_rejected	Paste the public key from the .pub file, never the private key.

Still stuck?

Email support@dekka.cloud with what you were doing and when, and the request_id if you have one from the API, which lets us find exactly what happened.