Troubleshooting: opening
Last updated 29 October 2026
Look up what you see when opening a database fails, or every request to it is refused: why, and what to do.
| What you see | Why | What to do |
|---|---|---|
open fails for a database you have not created | Opening never creates a database. A name with no database answers 404, and an attempt to create one through its URL answers 403 DATABASE_LIFECYCLE. | Create the database, wait until it is active, and open it again. |
Every request answers 401, or 404 for a database that exists | The access token is missing or expired, and db.status().replication.condition is unauthorized. | With a key, check that it is valid and not revoked. With a token file, check that the refresher runs and that the application started with URSULA_VFS_TOKEN_FILE set (see The refresher). |
open rejects with TonboError | The key or the lookup of the name failed. The error’s kind says which, and its message ends with the fix. | Follow the message (see Opening by name). |
An open by name rejects with UrsulaUnavailableError | The Management API did not answer before the signal fired: rate_limited, unavailable or unreachable. | Retry, or open the database by its URL, which skips the lookup. |