Look up what an environment variable changes and what an exit code or error code means, so a script can react to each failure correctly. For step-by-step fixes, see Troubleshooting.
Environment variables
| Variable | Effect |
|---|---|
GRAPHOPS_TOKEN | A service account API key (gsk_…). The CLI acts as that service account instead of your sign-in. |
GRAPHOPS_ORGANIZATION | Organization slug or ID for this command. A service account accepts only its own organization ID. |
GRAPHOPS_API_KEY | An API key for this command, instead of your organization's stored key. It is never stored. graphops exec passes it to your command. |
GRAPHOPS_CONFIG_DIR | Configuration directory. The default is ~/.config/graphops (or $XDG_CONFIG_HOME/graphops) on macOS and Linux and %APPDATA%\graphops on Windows, which is $env:APPDATA\graphops in PowerShell. |
GRAPHOPS_GRAPH_BIN, GRAPHOPS_SUBSTREAMS_BIN | Path of the graph or substreams binary to run, instead of the one the CLI finds. |
GRAPHOPS_AGENT | A short name for the coding agent running the CLI, up to 64 letters, digits, ., _ or -. Requests are marked as made by that agent, and the CLI never prompts. |
GRAPHOPS_NO_INPUT | Any value turns prompts off, as --no-input does. See Prompts at a terminal. |
GRAPHOPS_UPDATE_REGISTRY_URL | An npm registry mirror that graphops self-update and graphops doctor read the latest version from, instead of https://registry.npmjs.org. It must use HTTPS. |
HTTPS_PROXY, ALL_PROXY, HTTP_PROXY, NO_PROXY | The proxy for requests to GraphOps, and the hosts to reach without it. See Requests fail behind a proxy. |
SSL_CERT_FILE, SSL_CERT_DIR | On Linux, certificate authorities to trust instead of the system bundle. See Requests fail behind a proxy. |
NO_COLOR | Turns off colored output. |
The CLI ignores spaces and line breaks around GRAPHOPS_TOKEN and GRAPHOPS_API_KEY, so a value
saved with a trailing newline works. An empty GRAPHOPS_TOKEN counts as unset, and when the CLI
then finds no sign-in its error says that GRAPHOPS_TOKEN is empty.
To set a variable for the rest of your shell session, run export NAME=value on macOS and Linux,
$env:NAME = 'value' in PowerShell, or set NAME=value in Command Prompt. To unset it, run
unset NAME, Remove-Item Env:NAME or set NAME=.
The tools graphops runs never receive these variables. graphops exec sets only
GRAPHOPS_API_KEY, and SUBSTREAMS_API_KEY for Substreams.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Failure, such as a network error, an error from GraphOps or a tool that failed before deploying; graphops agent-skills check when a skill is out of date or new |
2 | Invalid command, a refused argument, an unsupported network, or graphops self-update of a copy it cannot update |
3 | Not signed in, the sign-in expired or needs to be recent, the service account API key was not accepted, or graphops auth status --check found no valid credential |
4 | No API key for your organization, or the stored key does not cover the data service |
5 | GraphOps refused the operation, including an organization you are not a member of; the JSON error.code names the reason |
6 | graphops subgraphs wait timed out |
120 | The npm package could not start graphops: there is no build for your system, such as Alpine Linux, or the package for your platform is not installed |
125 | graphops exec, or graphops substreams run, gui or sink, failed before running your command or the Substreams CLI, for example because a key is missing or an argument was refused |
126 | graphops exec, or graphops substreams run, gui or sink, found your command or the Substreams CLI but could not run it, for example because it is not executable |
127 | graph, substreams, the command for graphops exec, or the npm or brew that graphops self-update runs was not found |
130 | You cancelled at a prompt, with Ctrl+C or Esc, or answered no to a plan; nothing changed |
graphops exec ends with your command's exit code, and graphops substreams run, gui and sink
end with the Substreams CLI's. When they fail themselves, they exit 125, 126 or 127 instead
of 1, 2 or 4, so your script or process supervisor can tell their failures from those of the
program they run.
Error codes
With -o json, a command that fails prints one document on standard output,
{"error": {"code": "…", "message": "…", "retryable": false}}. Act on code, which stays the same
for the same failure, and show message to people: its wording can change. retryable is true
when running the same command again can succeed: the network failed, a request timed out, or
GraphOps answered 429, 502, 503 or 504. Wait before you retry, and wait longer after each
attempt.
Every error has a code. The CLI raises the codes below itself. Any other code comes from GraphOps
unchanged, and the error reference explains it. The exit code shown is the
code's own. graphops exec and graphops substreams run, gui and sink exit 125 instead for
every code except command_not_executable (126) and tool_not_found (127), so
argument_refused, for example, exits 2 for graphops subgraphs deploy and 125 for
graphops substreams run.
| Code | Exit code | Meaning |
|---|---|---|
network_error | 1 | A request could not reach GraphOps or another service it needs. Retryable. |
request_timeout | 1 | A request timed out. Retryable. |
platform_error | 1 | The platform answered with an error that carries no code. Retryable for 429, 502, 503 and 504. |
unexpected_response | 1 | A response the CLI cannot read, such as a record without a field it needs. |
request_invalid | 1 | The CLI could not build a request. |
config_invalid | 1 | A file the CLI keeps in its configuration directory does not parse. |
local_file_error | 1 | Reading, writing or locking a local file or directory failed. |
directory_unknown | 1 | The configuration or home directory cannot be determined; the message names the variable to set. |
secret_store_unavailable | 1 | No OS credential store is available for this operation. |
secret_store_failed | 1 | The OS credential store or secrets.toml failed, holds a malformed entry, or is readable by other users. |
secret_lost | 1 | A key was created but its secret could not be written to --secret-file; revoke the key. |
skills_unavailable | 1 | The GraphOps docs did not serve the agent skills index or a skill. |
skill_invalid | 1 | The agent skills index is not valid, or names a skill served from another site. |
skill_digest_mismatch | 1 | A downloaded agent skill does not match its published digest; nothing was written. |
graph_failed | 1 | graph deploy ended before GraphOps recorded the deploy. |
bridge_failed | 1 | subgraphs deploy could not start the local endpoint it gives graph deploy. |
process_failed | 1 | The CLI could not wait for a wrapped tool. |
signal_handlers_failed | 1 | The CLI could not install its signal handling around a wrapped tool. |
command_not_executable | 1 | The command or wrapped tool exists but cannot start (exit 126 for exec). |
substreams_info_failed | 1 | substreams info could not start. |
revocation_failed | 1 | auth logout could not revoke the refresh token (a warning; the session is still removed). |
usage | 2 | The arguments do not parse, or graphops init ran without a terminal. |
env_invalid | 2 | An environment variable is not valid UTF-8, or GRAPHOPS_AGENT is not 1 to 64 letters, digits, ., _ or -. |
profile_invalid | 2 | The profile is not defined, or one of its URLs is not https. |
json_unsupported | 2 | -o json on exec, substreams run, substreams gui, substreams sink, or self-update without --check. |
confirmation_mismatch | 2 | --confirm, or the name typed at a confirmation prompt, does not match the resource. |
confirmation_required | 2 | A change that removes access, such as an api-keys update that removes a product or changes a limit, needs --confirm. |
argument_refused | 2 | A graph deploy or Substreams argument that would change the endpoint, transport or credential, or a manifest on stdin (125 for substreams run, gui and sink). |
target_missing | 2 | No target given: an Endpoint Alias needs --cid, --managed-subgraph or --subgraph-id, a Subgraph lookup --cid or --subgraph-id. |
behavior_unsupported | 2 | --behavior does not apply to the Endpoint Alias's target type. |
time_invalid | 2 | A usage --from or --to that is not a time, date, word or duration the command takes. |
no_billing_period | 2 | usage --from period for an organization without a current billing period. |
timeout_invalid | 2 | A subgraphs wait --timeout that is not <n>s, <n>m or <n>h, or is too large. |
grants_invalid | 2 | --grants cannot be read or is not a JSON array of grants. |
grant_conflict | 2 | --add-grant and --remove-grant name the same permission. |
grant_not_held | 2 | --remove-grant names a permission the service account does not hold. |
nothing_to_change | 2 | service-accounts update without a change. |
api_key_unknown | 2 | An API key name or ID that names no key of the organization, or a value shaped like a key's secret. |
api_key_ambiguous | 2 | An API key name that several keys share; pass an ID. |
like_not_query_key | 2 | api-keys create --like names a service account API key; it copies a query key. |
key_already_stored | 2 | api-keys create --store without --replace while a key is stored for the organization. |
key_empty | 2 | api-keys store read no key from stdin. |
key_invalid | 2 | api-keys store read something that is not a query key (gqk_…) with a valid checksum. |
token_empty | 2 | auth login --with-token read no token from stdin. |
stdin_unreadable | 2 | stdin could not be read. |
secret_file_unusable | 2 | The --secret-file cannot be created, for example because it exists. |
network_requires_substreams | 2 | exec --network without a key that covers Substreams or --product substreams. |
command_missing | 2 | exec without a command after --. |
unsupported_network | 2 | GraphOps does not serve Substreams for the network. |
network_repeated | 2 | --network given more than once. |
network_missing | 2 | --network without a value. |
network_undetermined | 2 | No --network, and the manifest is not first or substreams info cannot read it. |
webhook_url_missing | 2 | substreams sink webhook without the URL first. |
sink_unsupported | 2 | substreams sink <kind> for a kind other than noop, protojson or webhook. |
service_account_credential_invalid | 2 | GRAPHOPS_TOKEN starts with gsk_ but is not a well-formed service account API key. |
query_key_not_supported | 2 | GRAPHOPS_TOKEN holds a query key (gqk_), which works only with data services. |
organization_not_selected | 2 | No organization is configured and you are a member of several (or none). |
organization_mismatch | 2 | The configured organization is not the service account's own organization ID. |
coding_agent_not_found | 2 | agent-skills install found no coding agent; pass --agent. |
skill_unknown | 2 | An agent skill name that GraphOps does not publish. |
self_update_unsupported | 2 | self-update of a graphops that Homebrew or a global npm install did not install, such as a release archive, a build from source or a project's node_modules; the message says how to update it. |
not_signed_in | 3 | No session and no GRAPHOPS_TOKEN, or GRAPHOPS_TOKEN is set but empty. |
session_expired | 3 | The stored session expired and could not be refreshed, or the platform no longer accepts it. |
session_invalid | 3 | The stored session is missing from the credential store or cannot be read. |
credential_rejected | 3 | The platform did not accept the credential and sent no code of its own; for auth status --check, a GRAPHOPS_TOKEN it rejected. |
unverified | 3 | auth status --check could not verify the credential, for example offline. Retryable when the cause is. |
id_token_missing | 3 | The session has no ID token, or a refresh returned none. |
sign_in_unavailable | 3 | Device sign-in is not available for this profile. |
sign_in_denied | 3 | The sign-in was denied in the browser. |
sign_in_expired | 3 | The sign-in code expired before it was approved. |
sign_in_failed | 3 | The sign-in server refused or ended the sign-in, or returned a session without an expiry. |
session_required | 3 | A person-only command run with a service account credential. |
missing_key | 4 | No GRAPHOPS_API_KEY and no stored API key for the selected organization, or the stored key's secret is missing (125 under exec). |
key_missing_product | 4 | The stored API key does not cover a data service exec --product names, or Substreams for the Substreams commands (125 under exec). |
not_found | 5 | No Managed Subgraph, Endpoint Alias, API key or service account has that name or ID. |
next_missing | 5 | The Managed Subgraph has no staged Next version. |
next_changed | 5 | The staged Next version is not the one --expect-next names. |
next_occupied | 5 | A different Next version is staged; pass --replace-next to replace it. |
schema_incompatible | 5 | The new version's schema removes or changes query definitions; pass --accept-schema-changes. |
managed_subgraph_deleting | 5 | The Managed Subgraph is being deleted. |
managed_subgraph_suspended | 5 | The Managed Subgraph is suspended. |
deployment_failed | 5 | The version subgraphs wait watches failed to index. |
key_revoked | 5 | api-keys store of a revoked key. |
no_data_services | 5 | api-keys create --store without products for an organization with no data services. |
target_not_synced | 5 | The version an Endpoint Alias would serve is not synced and healthy; pass --force to change it anyway. |
wait_timeout | 6 | subgraphs wait timed out. |
launch_failed | 120 | The npm package could not start graphops: no build for this system, such as musl Linux, or the platform package is not installed. |
tool_not_found | 127 | The wrapped tool, or the command exec runs, is not found. |
cancelled | 130 | A person cancelled at a prompt: Ctrl-C or Esc, or No to a plan. Only at a terminal. |
Next steps
Last updated