Error codes
The full table of errors the coordinator's client-facing gRPC API returns: the stable numeric code, its name, the gRPC status a client sees, what it means and the usual fix. Also covers the validation limits on job metadata and the allow_client_random_seed gate.
The coordinator answers a failed RPC with a gRPC status: a status code and a human-readable message. Each application error below has a stable numeric code and name, listed in the coordinator API reference.
In 1.4.0-alpha the coordinator sends only the gRPC status code
and message. It does not attach the ApiError message (code,
name, message) to the status details, though the proto describes
it. To tell errors apart, match on the gRPC status code and the
message text shown below.
Error table
| Code | Name | gRPC status | Meaning | Typical fix |
|---|---|---|---|---|
1001 | JOB_NOT_FOUND | NOT_FOUND | Job not found: <job_id>. The job ID is unknown: it was never created, its finished job was evicted after job_ttl_seconds, or the coordinator restarted. | Check the job ID. After a coordinator restart, submit the job again. Raise job_ttl_seconds if clients poll finished jobs late. |
1002 | PROGRAM_NOT_FOUND | NOT_FOUND | Program not found: <hash_id>. No guest program with this hash is registered. | Register the ELF (RegisterGuestProgram) before setting it up or proving it. |
1003 | PROGRAM_NOT_SETUP | NOT_FOUND | Program exists but setup is not complete: <hash_id>. The program is not set up on the workers, either never or not since the coordinator started. | Run the setup for the program, and again after every coordinator restart. |
1004 | INVALID_JOB_STATE | INVALID_ARGUMENT | Invalid job state: <reason>. The request is not valid for the job or the cluster: for example minimal_compute_capacity must not exceed compute_capacity, an explicit capacity of 0, or a PushJobInput message with no chunk. | Read the reason and fix the request. |
1005 | INVALID_PROOF_CONVERSION | INVALID_ARGUMENT | Invalid proof conversion: <from> → <to>. The proof kind can't be converted to the requested destination. | Ask for a supported proof_dest. The 1.4.0-alpha coordinator backend doesn't return this code. |
1006 | CLIENT_RANDOM_SEED_NOT_ALLOWED | PERMISSION_DENIED | Client-supplied random seeds are not allowed by this coordinator. The request carried a random seed and allow_client_random_seed is false. | Send the request without a seed, or have the operator enable the gate. See Random seed gate. |
1007 | JOB_METADATA_NOT_ALLOWED | PERMISSION_DENIED | Job metadata is not allowed by this coordinator. The request carried metadata and allow_job_metadata is false. | Send the request without --metadata / .metadata(), or have the operator enable the gate. See Job metadata. |
1008 | SNARK_UNAVAILABLE | FAILED_PRECONDITION | Final SNARK unavailable: <reason>. A final-SNARK proof was requested but the workers can't produce it: the workers have no SNARK proving key, or their key is set up for another protocol than the one asked for. | Start every worker with --snark and a SNARK proving key of the protocol you want. See zisk-worker / Proving keys and Choosing a proof format. |
1009 | INPUT_TOO_LARGE | INVALID_ARGUMENT | Input too large: the guest's input region holds at most 2147483632 bytes. The input pushed to the job is larger than the guest's 2 GiB − 16 bytes input region. The job fails. | Shrink the input. The limit is fixed by the guest memory map. |
2001 | CLUSTER_UNAVAILABLE | UNAVAILABLE | Cluster unavailable: <reason>. The cluster can't take the job now. The reason is one of the messages listed below. | Retry with backoff, add workers, or lower the requested capacity or min_compute_units. |
3001 | INTERNAL | INTERNAL | An internal error occurred. An unexpected server error. The detail is logged on the coordinator only, never sent to the client. | Look for the internal coordinator error line in the coordinator log at the time of the call. |
CLUSTER_UNAVAILABLE reasons
| Reason in the message | What it means |
|---|---|
insufficient ready capacity for the request | Not enough ready compute units for the job's minimum. |
workers are setting up; retry shortly | Some workers are recovering from a cancelled or failed job and will be ready shortly. |
workers are busy running another job; retry shortly | Workers are computing another job. |
workers connected but setup not done; call setup() first | Workers are connected but no program is set up on them. |
Request validation errors
Some malformed requests are rejected before they reach the
backend, with gRPC status INVALID_ARGUMENT and no numeric code:
| Message | Cause |
|---|---|
zisk_elf must not be empty | RegisterGuestProgram with an empty ELF. |
job_kind must be set | A JobRequest with no job kind. |
invalid UUID: <id> | A job ID that isn't a UUID. |
PushJobInput stream must not be empty / chunk must be set | A PushJobInput or PushJobHintsInput stream with no first chunk. |
<kind> jobs do not take metadata | Metadata on a setup job. See Job metadata. |
metadata has too many entries (<n> > 32) | More than 32 metadata entries. |
metadata key too long (<n> > 128 bytes) | A metadata key over 128 bytes. |
metadata value for key "<k>" too long (<n> > 1024 bytes) | A metadata value over 1024 bytes. |
Job metadata
A JobRequest can carry caller-defined key/value labels in
metadata. From the CLI, pass --metadata KEY=VALUE (repeatable)
to cargo-zisk remote; from the
SDK, call .metadata(key, value) on the request.
| Limit | Value | On violation |
|---|---|---|
| Entries per request | 32 | INVALID_ARGUMENT |
| Key length | 128 bytes | INVALID_ARGUMENT |
| Value length | 1024 bytes | INVALID_ARGUMENT |
| Job kinds that take it | prove, execute, wrap, aggregate | A non-empty map on a setup job (setup, setup_aggregation_program) gets INVALID_ARGUMENT |
| Coordinator gate | allow_job_metadata (default true) | JOB_METADATA_NOT_ALLOWED (1007) |
An empty map counts as no metadata. The coordinator keeps the
metadata with the job and appends it as k: v, k: v to the line
it logs when the job finishes. That suffix is capped at 512 bytes,
ending in … when truncated, and control characters (newlines,
tabs) are replaced with spaces.
Random seed gate
Every prove and execute job runs with a 256-bit host randomness
seed. The guest reads values derived from it through
zkvm_random_u64 (see Host randomness).
By default the coordinator draws a fresh seed for each job and
returns it with the result, so the run can be replayed.
A client can send its own seed, for example --random-seed <HEX>
on cargo-zisk remote, to
replay a run. The coordinator accepts it only when the core
config sets:
[coordinator]
allow_client_random_seed = true
When the option is false (the default), a job that carries a
seed is rejected with CLIENT_RANDOM_SEED_NOT_ALLOWED (1006)
before it runs. When it is true, the coordinator logs
[Job] Using a client-supplied random seed: <seed> for each such
job.
Enable the gate only for trusted clients (replays, CI). A client that picks both the seed and the input can craft an input that is expensive under that seed, for example by forcing hash collisions.