Limits and errors#
This page lists Hesperus's limits in one place, then every error code its
routes return. Errors are JSON objects {code, message, detail}: match on
code (see Errors for the format).
Limits#
Names and notebooks#
| Item | Limit |
|---|---|
| Notebook, runtime and environment name | Lowercase letters, digits and -, starting with a letter, not ending with -, at most 40 characters |
| A new notebook runtime's name | <notebook>-<6 hex digits> (the notebook's name cut to 33 characters) |
| Notebook title | 200 characters |
| Notebook description | 2000 characters |
| Notebook file | A .ipynb path inside the drive, no .., at most 1024 characters; default notebooks/<name>.ipynb |
Resources#
| Item | Limit |
|---|---|
| CPU cores | 1 to 256; default 2 (it may use idle cores beyond them) |
| Memory | 512 MiB to 4 TiB; default 4 GiB; a hard limit |
| GPUs | 0 to 16; default 0 |
| GPU models | At most 8, each at most 64 characters |
| GPU memory per GPU | 0 to 1024 GB |
| Isolation | standard (default) or sandbox; SSH and the IDE need standard |
Drives and credentials#
| Item | Limit |
|---|---|
The drive at /content |
notebooks for a notebook, <name>-home for an environment (both made on first use), or any existing drive |
| Other drives | At most 16; absolute mount paths up to 512 characters, apart from each other, from /content and from the system's directories |
| Credentials as variables | At most 32; variable names [A-Z_][A-Z0-9_]*, at most 128 characters, not the runtime's own |
Setup#
| Item | Limit |
|---|---|
| pip requirements | At most 64, each at most 256 characters, no options |
| Packages | At most 64, each at most 128 characters (with =version) |
| Script | 16 KiB, run with sh as root |
| Package lists cache | Refreshed when older than a week |
Idle stop and lifetimes#
| Item | Limit |
|---|---|
| Idle stop | 5 to 1440 minutes; default 30 for a notebook's runtime, 60 for an environment; 0 (never) for workspace admins only |
astra ssh waits for a runtime |
15 minutes |
| SSH certificate | 8 hours (valid from 5 minutes before it was issued); astra renews one with less than 10 minutes left |
| Link to an IDE or an app | Once, within 60 seconds |
| A browser signed in to an IDE or an app | 8 hours, at that address only |
Sharing, apps and sessions#
| Item | Limit |
|---|---|
| Members of a runtime | 50 |
| Named apps of a runtime | 16; names at most 40 characters |
| Ports an app may not use | 2222 (SSH); 8888 in a notebook's runtime (Jupyter); 8822 in an IDE environment (the IDE) |
| SSH sessions kept per runtime | The last 50 |
| Limits per person | Environments at once: 0 (none) to 1000. GPUs at once: 0 (none) to 10000 |
Errors#
| HTTP | Code | When | What to do |
|---|---|---|---|
| 400 | INVALID_NOTEBOOK |
A field is out of range or malformed. The message names it: spec.resources.memory_bytes: 512 MiB to 4 TiB, spec.idle_timeout_minutes: 5 to 1440 (0: never, the workspace's admins only), spec.drives[0].mount_path: /usr/local/x is a system directory; use one of its own, like /data/d, drive weights does not exist: create it first, spec.ssh: SSH needs standard isolation (a sandboxed runtime's network is gVisor's own), spec.ssh.enabled: a shell runtime is reached over SSH only; it cannot be off, spec.apps[0].port: port 2222 is the runtime's SSH server's, public_key: … | Fix the field. |
| 403 | NAMESPACE_FORBIDDEN |
Opening a notebook with a runtime, drive or credential of another workspace: … is not in this namespace. | Name your workspace's own. |
| 403 | RBAC_FORBIDDEN |
Your role does not allow it: viewers read notebooks and runtimes but open, start, stop, connect to and make nothing; only admins set the limits per person. | Ask a workspace admin for the role. |
| 403 | SSH_FORBIDDEN |
SSH, an IDE link or an app link for a runtime you neither own nor share: runtime dev is user:…'s: only its owner, the people it is shared with and the workspace's admins may connect to it. Changing its members as someone else: only runtime dev's owner and the workspace's admins share it. | Ask its owner to share it. |
| 403 | IDE_FORBIDDEN, APP_FORBIDDEN |
A request to an IDE's editor or an app by someone who may not use the runtime (for example after being taken off its members). | As above. |
| 403 | IDE_ORIGIN |
An IDE opened anywhere but its own address: an IDE is opened on its own address, not through the console's: use Open IDE (or astra env open). |
Use Open IDE. |
| 403 | ADMIN_ONLY |
only the workspace's admins make a runtime for someone else; idle_timeout_minutes 0 (never stopped when idle) is for the workspace's admins: a shared environment that stays up. Choose 5 to 1440 minutes | Ask a workspace admin. |
| 404 | NOTEBOOK_NOT_FOUND |
Notebook not found. | Check the name. |
| 404 | NOTEBOOK_RUNTIME_NOT_FOUND |
Runtime not found. | Check the name (astra env list). |
| 409 | NOTEBOOK_ALREADY_EXISTS |
runtime dev already exists, notebook mnist already exists. | Choose another name. |
| 409 | NOTEBOOK_CONFLICT |
runtime dev is stopping; start it when it has stopped; runtime mnist-3fa91c has no SSH (turn it on: ssh.enabled); runtime dev has no IDE (it is a shell runtime); … is being changed; try again. | Wait, or use what it has. |
| 409 | HESPERUS_LIMIT |
Over the workspace's limits per person, when a runtime is made, started or a notebook opened: this workspace allows 2 environments running at once per person, and its owner has 2 (dev, code): stop one first, or this workspace allows 4 GPUs per person across their environments and notebooks, and its owner holds 4 (dev): this one asks for 1; stop one first or ask for fewer. | Stop one of the runtimes it names, or ask for fewer GPUs. |
| 409 | RUNTIME_NOT_RUNNING |
An IDE or app link for a runtime on no machine: code is stopped: start it first, then open it once it is ready. | Start it. |
| 409 | RUNTIME_DOMAIN_UNSET |
This console serves no runtime pages, so IDEs and apps cannot be opened. SSH works without them. | Use SSH. |
| 400 | INVALID_NAME, INVALID_PORT, INVALID_PATH |
A runtime link with a malformed runtime name, a port of 0, or a path not starting with /. |
Fix the request. |
| 500 | NOTEBOOK_STORE_FAILURE |
An internal failure. | Try again; if it persists, contact support. |
Both per-person limits are checked when a runtime is made or started,
against what its owner already has Pending, Starting or Ready; two
starts at the same instant may both pass. Runtimes already running are
never stopped by a limit.
Why a runtime stopped or failed#
Its status.reason says:
| Reason | Meaning |
|---|---|
| Stopped by user:… | A person stopped it. |
| Stopped after 60 minutes idle | Its idle stop. |
| Jupyter Server exited, Its SSH server exited, Its IDE (code-server) exited | Its server ended: the runtime is Stopped. |
| Its run could not be made: … | For example a preset with no build for the machines' GPUs. Failed. |
| Its run … was deleted | Its run was deleted from outside Hesperus. Failed. |
| … runs on gpu-01, but its agent is too old to say it is ready: update the agent (Machines → gpu-01 → Update) | The machine's agent predates Hesperus. Stays Starting. |
A runtime whose own start failed inside the container says why in its run's log: an image without the SSH user (user dev does not exist in this image: set the runtime's ssh.user to one of its users), an IDE on a musl image, or an agent too old to mount the IDE (update the agent (Machines → the machine → Update)). See Troubleshooting.