Troubleshooting

Look up the error message or symptom you see to find its cause and the fix. Startup errors land in the container log, which docker compose logs umpteenth shows.

localhost inside the container

Umpteenth runs in a container, and inside it localhost and 127.0.0.1 mean the container itself. A localhost URL that works in your browser on the Docker host fails in Umpteenth for any service on the host: an identity provider, Ollama or LM Studio, an MCP server or a notification receiver.

Give Umpteenth an address that leads to the host:

1. Let the service on the host listen on more than 127.0.0.1, for example on 0.0.0.0.
2. On Linux, add extra_hosts: ["host.docker.internal:host-gateway"] to the umpteenth service in docker-compose.yml and run docker compose up -d.
3. Use http://host.docker.internal:<port> in Umpteenth, or the host’s LAN address.

Models and costs walks through this for Ollama and LM Studio. Your browser and the container use the same issuer URL, so give an identity provider a hostname that both reach.

To test an address from the container’s point of view, run a throwaway curl in its network:

docker run --rm --network container:umpteenth curlimages/curl -sS https://id.example.com/.well-known/openid-configuration

Starting up

app.encryption_key (APP_ENCRYPTION_KEY) is required

Umpteenth has no encryption key, either because config.yml lacks app.encryption_key or because Umpteenth found no config file. If config.yml didn’t exist before the first docker compose up, Docker created a directory named config.yml in its place, and Umpteenth doesn’t read a directory as a config file. Remove that directory, copy config.example.yml to config.yml, fill it in and start again (Configuration).

app.encryption_key (APP_ENCRYPTION_KEY) must be at least 16 bytes means the key is too short. openssl rand -base64 32 prints one that fits.

config.yml: line 12: unknown option ...

The file sets an option that doesn’t exist, because of a typo or a line indented under the wrong section. Compare it with config.example.yml. Other errors at start name the option or its environment variable, such as unknown log.level (LOG_LEVEL) "verbose", use debug, info, warn or error.

A setting has no effect

An environment variable has to spell the option’s path in upper case, with underscores for dots and hyphens, such as SERVER_TRUST_PROXY for server.trust_proxy or AUTH_PROVIDERS_POCKET_ID_ISSUER for auth.providers.pocket-id.issuer. Umpteenth ignores variables with any other name without a warning, except under AUTH_PROVIDERS_, and treats an empty variable as unset. A line in the .env file next to docker-compose.yml reaches Umpteenth only if the service passes it on, through environment: or env_file: (Configuration).

Umpteenth reads config.yml at start, so restart the container after an edit.

... doesn't end in an option of auth.providers

An environment variable starts with AUTH_PROVIDERS_ and ends in no option name, such as AUTH_PROVIDERS_POCKET_ID_ISUER. Umpteenth reads the provider ID from the part between the prefix and the option name, so it refuses a variable it can’t split. Fix the name against the sign-in options.

auth.providers.github.client_secret (AUTH_PROVIDERS_GITHUB_CLIENT_SECRET) is required

A github provider needs the client secret of its OAuth app. config.example.yml comes with a github provider that has none, so if you copied the file and sign in another way, delete that block. Errors about other providers and options read the same way, such as a missing type or name, and Configuration lists the options each type needs.

... has to list who may sign in, since anyone with a GitHub account could otherwise

The github provider lists neither allowed_users nor allowed_organizations. Any GitHub account can authorize an OAuth app, so add the usernames or organizations that may sign in (Sign-in).

... only applies to github providers

A provider sets an option of the other type, such as allowed_users on an oidc provider. The message ends in only applies to oidc providers for issuer or allowed_groups on a github provider. Remove the option, or fix the provider’s type.

failed to reach the container engine

Umpteenth can’t connect to Docker or Podman, and refuses to start without an engine. Check that the compose file mounts the engine’s socket at /var/run/docker.sock, or that DOCKER_HOST points at it. On Podman, start the user’s API socket first (Installation).

Failed to prepare the sandbox backend

The log line comes with failed to prepare the default sandbox image, and every run fails with Failed to create the sandbox: .... The engine lacks the sandbox image, and the pull failed because the project doesn’t publish it yet. Build it as in Installation, with podman build if Umpteenth uses Podman.

failed to decrypt secret ...

This error, or failed to decrypt provider API key, means the encryption key changed after Umpteenth stored the value. Put the old app.encryption_key back. If you lost it, create the secrets, model API keys and MCP logins again, since Umpteenth can’t decrypt them without the old key (Backups and migration).

Signing in

The login page shows the reason a sign-in failed.

Sign-in is not configured

The login page shows no sign-in button because auth.providers lists no provider. Add one to config.yml as in Sign-in and restart.

The service is temporarily unavailable, please try again

Umpteenth couldn’t reach the sign-in provider. For an oidc provider, it gives up loading the identity provider’s configuration after 10 seconds. The issuer URL has to work from inside the container (see localhost inside the container), and it has to match the issuer value the identity provider publishes character for character, trailing slash included. For a github provider, the container needs to reach github.com and api.github.com.

Sign-in failed, please try again

The sign-in provider sent you back, and Umpteenth couldn’t complete the sign-in. Check three things:

• The provider’s client_secret matches the secret of the client or GitHub OAuth app.
• You opened Umpteenth at app.url and at no other address, since the sign-in starts and ends there.
• You finished at the sign-in provider within 10 minutes.

Your account is not allowed to use Umpteenth

The provider you signed in with doesn’t admit your account.

For an oidc provider, its allowed_groups lists groups, and the ID token’s groups claim contains none of them. Group names have to match as written, upper and lower case included. Add the user to a listed group, or make the identity provider put the groups claim into the ID token.

For a github provider, allowed_users lacks the username, and the account isn’t an active member of an organization in allowed_organizations. Accept a pending invitation to the organization first. If the organization restricts access for OAuth apps, an owner has to approve the app on GitHub before Umpteenth can see the membership. After a rename on GitHub, put the new username into allowed_users.

Your account has been deactivated, ask an admin to reactivate it

An instance admin deactivated your user under Admin → Users, which ends your sessions and refuses your sign-ins until they click Reactivate.

The sign-in provider denied access

The sign-in provider refused the sign-in, for example because the user isn’t assigned to the client in the identity provider, or clicked Cancel on GitHub’s authorization page. Fix the assignment in the identity provider, or sign in again and authorize the app.

The sign-in provider rejects the redirect URI

Register <app.url>/api/auth/callback/<id> with the provider, where <id> is the provider’s key under auth.providers, for example https://umpteenth.example.com/api/auth/callback/pocket-id. On GitHub, that’s the OAuth app’s Authorization callback URL, which takes a single URL, so each Umpteenth instance needs an OAuth app of its own. The redirect URI changes with the ID and with app.url, so keep app.url equal to the URL you open.

This sign-in option is no longer available

The sign-in started or came back with a provider ID that auth.providers doesn’t list anymore, because you renamed or removed the provider after the login page loaded. Reload the login page and sign in again.

Too many requests while signing in

Umpteenth allows 20 requests per minute from one client address to its sign-in endpoints. Past that, your browser shows a JSON error with the message Too many requests in place of the login page. Behind a reverse proxy without server.trust_proxy: true, every user shares the proxy’s address and its limit (Reverse proxy).

Workspaces and roles

Only admins of the workspace can do this

Your role in the workspace is Member, and the change needs an admin, such as editing providers or Settings → General. An admin can change your role under Settings → Members. An API token gets the same answer, since it acts with the role of the user who created it.

This can only be done while signed in, not with an API token

API tokens can’t manage members, invites, workspaces or other tokens, so make that change in the browser.

Workspaces are turned off on this instance

workspaces.enabled is off, so everyone shares one workspace and nobody creates, joins or deletes another. Turn it on as Workspaces shows.

An invited person gets a workspace of their own instead

Umpteenth matched no email invite at their sign-in. It matches only an address the sign-in provider marks as verified, so an OpenID Connect provider has to send email_verified as true. The invite may have expired as well, or name another address, which Pending invites under Settings → Members shows. Send an invite link instead, which works whatever the address.

The workspace has 2 active runs, wait for them to finish or cancel them first

Umpteenth deletes a workspace only after its queued and running runs have ended. Cancel them under Runs, or wait for them to finish, and delete the workspace again.

Models

Compiling failed

The alert on the New job page reads “The model could not compile the job” when the model call fails, and the container log has the cause in a Request failed line. Umpteenth compiles with the Utility default model, or with the Agent default if you set no Utility model. After a fresh install, the usual cause is the Anthropic provider without an API key: paste yours as in Installation. “Set a utility model in Settings to compile jobs” means you set neither default. Fill in manually skips compiling.

No model is configured

The run failed before it started with “No model is configured. Pick a model for the job or set a default agent model in Settings.” Neither the job nor Settings → General → Default models names an agent model (Models and costs).

Sync failed

A provider row under Settings → Providers & models shows Sync failed, with the error in its tooltip. For Ollama and LM Studio, the preset’s localhost address is the usual cause (see localhost inside the container). the server's model list is not JSON means the Base URL has to end where the server serves /models, such as /v1.

points to a private or local network address

Saving a provider, an HTTP MCP server or the notification webhook fails with this message when network.allow_private_targets is false. Use a public address or turn the option back on (Security).

The workspace reached its daily spend limit of $5.00

Runs fail at start once the day’s spend reaches Daily spend limit under Settings → General → Spend and retention. The day resets at 00:00 UTC (Models and costs).

Sandboxes and runs

Internet sandboxes can reach private networks

The Sandbox backend card under Settings → General shows this alert with Egress firewall set to Not enforced. Umpteenth couldn’t install the firewall rules that keep sandboxes off your network, which is always the case on Podman. Security explains the options, and sandbox.egress_filter: required makes Umpteenth refuse internet runs until the rules are in place.

Sandboxes can’t start under the configured runtime

Umpteenth’s test sandbox failed to start under sandbox.docker.runtime, and runs fail until you fix the runtime and restart Umpteenth (gVisor).

Environment build failed: ...

The job’s Dockerfile has no successful build. Read the build log on the job’s Environment tab (Sandboxes).

The setup script failed with exit code 1

The setup script in the job’s playbook failed, and its step on the Timeline shows the output. Fix the script on the Playbook tab or roll back to an earlier version (How jobs learn).

the run exceeded its limit of 60 turns

The run hit one of its job’s limits. The turn limit and the cost limit (the run exceeded its cost limit of $2.00) end a run as Failed, and the time limit (the run exceeded its time limit) ends it as Timed out. Raise the limit in the Sandbox card on the job’s Settings tab (Managing jobs), or make the instruction more specific (Writing instructions).

interrupted: the replica executing this run stopped responding

Umpteenth stopped, crashed or lost a replica while the run was in flight, and it doesn’t restart such runs. The shorter interrupted: the replica executing this run stopped has the same cause. Click Retry on the run page if running the job again is safe (Upgrades and maintenance).

The retry was skipped because the job is already running

The job’s When runs overlap setting is Skip, and another run of it is active (Triggers and schedules).

The run page stops updating

Behind a reverse proxy, turn off response buffering and allow long read timeouts so live updates get through (Reverse proxy). Reload the page to see the recorded timeline.

state keys and values of a job may total at most 16 MiB

A ump state set or an edit on the job’s State tab would take the job’s state past 16 MiB of keys and values. Delete keys the job no longer needs on the State tab, or have its script keep less, such as IDs instead of whole items (Managing jobs). A state that grew past 16 MiB before Umpteenth had this limit makes ump state list fail with “The job’s state holds more than 16 MiB, so reading all of it at once fails until you delete keys the job no longer needs”, and the same deletions fix it.

No events

An old run’s Timeline is empty once retention has removed its events (Reading a run).

A job never graduates

Work through the checklist on How jobs learn.

Webhooks and notifications

A webhook answers 401

The response carries Token is invalid or expired. The request needs the job’s webhook token in an Authorization: Bearer <token> header, and an API token doesn’t work there. A new job has no webhook token until you click Generate token, and Rotate token invalidates the old one (Triggers and schedules). The webhook URL of a deleted job answers 401 too.

A webhook answers 429

Umpteenth accepts 60 webhook calls per minute for each job, with bursts of up to 30. Wait for the number of seconds in the Retry-After header.

A webhook answers 200 with "status": "skipped"

You paused the job, or its When runs overlap setting is Skip and a run is active. For a paused job, the response has an empty runId and Umpteenth records no run (Managing jobs).

No notifications arrive

Click Send test on the Notifications card under Settings → General. A failed test shows “The webhook did not accept the notification:” followed by the receiver’s error, and the log shows The notification webhook rejected a delivery for a message the receiver refused (Notifications).

MCP servers

Mentions github, but no MCP server with that name is configured

The compile step matches services in the instruction to MCP servers by name. Add the server under MCP Servers with the name the instruction uses, then compile again (MCP servers).

MCP server github is unavailable: ...

The run’s Timeline shows this line if a server failed to connect or took longer than two minutes, and the run continued without it. For an expired login, the message reads “The OAuth login expired. Log in again under MCP Servers.” A stdio server started with npx or uvx needs Internet access in the job to download its package (MCP servers).

An MCP login doesn’t return to Umpteenth

The provider sends your browser back to <app.url>/api/mcp-servers/<server id>/oauth/callback, so app.url has to be the address you use for Umpteenth (MCP servers).