--- title: Troubleshooting description: Fixes for failed builds, deploys stuck on Starting, reference and DNS errors, plan and spend limits, invitations and the other errors people hit most. section: Help order: 1 --- 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](/docs/build-configuration), 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](/docs/config-as-code#what-if-the-file-is-wrong) 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.` 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](/docs/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](/docs/billing#what-happens-at-the-spend-limit). ## 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](/docs/organisations#accept-an-invitation). ## 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](/docs/sign-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](/docs/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](/docs/ai-routing). `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](/docs/ai-keys). `endpoint_unavailable` means you called a `private/` 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](/docs/gpu-instances#call-an-endpoint-through-the-ai-gateway). ## 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](/docs/gpu-instances#join-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](mailto: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.