Skip to content

Reference

GraphOps CLI environment variables, exit codes and error codes, for scripts and process supervisors that act on how a command ended.

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

VariableEffect
GRAPHOPS_TOKENA service account API key (gsk_…). The CLI acts as that service account instead of your sign-in.
GRAPHOPS_ORGANIZATIONOrganization slug or ID for this command. A service account accepts only its own organization ID.
GRAPHOPS_API_KEYAn 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_DIRConfiguration 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_BINPath of the graph or substreams binary to run, instead of the one the CLI finds.
GRAPHOPS_AGENTA 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_INPUTAny value turns prompts off, as --no-input does. See Prompts at a terminal.
GRAPHOPS_UPDATE_REGISTRY_URLAn 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_PROXYThe proxy for requests to GraphOps, and the hosts to reach without it. See Requests fail behind a proxy.
SSL_CERT_FILE, SSL_CERT_DIROn Linux, certificate authorities to trust instead of the system bundle. See Requests fail behind a proxy.
NO_COLORTurns 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

CodeMeaning
0Success
1Failure, 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
2Invalid command, a refused argument, an unsupported network, or graphops self-update of a copy it cannot update
3Not 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
4No API key for your organization, or the stored key does not cover the data service
5GraphOps refused the operation, including an organization you are not a member of; the JSON error.code names the reason
6graphops subgraphs wait timed out
120The 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
125graphops 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
126graphops 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
127graph, substreams, the command for graphops exec, or the npm or brew that graphops self-update runs was not found
130You 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.

CodeExit codeMeaning
network_error1A request could not reach GraphOps or another service it needs. Retryable.
request_timeout1A request timed out. Retryable.
platform_error1The platform answered with an error that carries no code. Retryable for 429, 502, 503 and 504.
unexpected_response1A response the CLI cannot read, such as a record without a field it needs.
request_invalid1The CLI could not build a request.
config_invalid1A file the CLI keeps in its configuration directory does not parse.
local_file_error1Reading, writing or locking a local file or directory failed.
directory_unknown1The configuration or home directory cannot be determined; the message names the variable to set.
secret_store_unavailable1No OS credential store is available for this operation.
secret_store_failed1The OS credential store or secrets.toml failed, holds a malformed entry, or is readable by other users.
secret_lost1A key was created but its secret could not be written to --secret-file; revoke the key.
skills_unavailable1The GraphOps docs did not serve the agent skills index or a skill.
skill_invalid1The agent skills index is not valid, or names a skill served from another site.
skill_digest_mismatch1A downloaded agent skill does not match its published digest; nothing was written.
graph_failed1graph deploy ended before GraphOps recorded the deploy.
bridge_failed1subgraphs deploy could not start the local endpoint it gives graph deploy.
process_failed1The CLI could not wait for a wrapped tool.
signal_handlers_failed1The CLI could not install its signal handling around a wrapped tool.
command_not_executable1The command or wrapped tool exists but cannot start (exit 126 for exec).
substreams_info_failed1substreams info could not start.
revocation_failed1auth logout could not revoke the refresh token (a warning; the session is still removed).
usage2The arguments do not parse, or graphops init ran without a terminal.
env_invalid2An environment variable is not valid UTF-8, or GRAPHOPS_AGENT is not 1 to 64 letters, digits, ., _ or -.
profile_invalid2The profile is not defined, or one of its URLs is not https.
json_unsupported2-o json on exec, substreams run, substreams gui, substreams sink, or self-update without --check.
confirmation_mismatch2--confirm, or the name typed at a confirmation prompt, does not match the resource.
confirmation_required2A change that removes access, such as an api-keys update that removes a product or changes a limit, needs --confirm.
argument_refused2A 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_missing2No target given: an Endpoint Alias needs --cid, --managed-subgraph or --subgraph-id, a Subgraph lookup --cid or --subgraph-id.
behavior_unsupported2--behavior does not apply to the Endpoint Alias's target type.
time_invalid2A usage --from or --to that is not a time, date, word or duration the command takes.
no_billing_period2usage --from period for an organization without a current billing period.
timeout_invalid2A subgraphs wait --timeout that is not <n>s, <n>m or <n>h, or is too large.
grants_invalid2--grants cannot be read or is not a JSON array of grants.
grant_conflict2--add-grant and --remove-grant name the same permission.
grant_not_held2--remove-grant names a permission the service account does not hold.
nothing_to_change2service-accounts update without a change.
api_key_unknown2An API key name or ID that names no key of the organization, or a value shaped like a key's secret.
api_key_ambiguous2An API key name that several keys share; pass an ID.
like_not_query_key2api-keys create --like names a service account API key; it copies a query key.
key_already_stored2api-keys create --store without --replace while a key is stored for the organization.
key_empty2api-keys store read no key from stdin.
key_invalid2api-keys store read something that is not a query key (gqk_…) with a valid checksum.
token_empty2auth login --with-token read no token from stdin.
stdin_unreadable2stdin could not be read.
secret_file_unusable2The --secret-file cannot be created, for example because it exists.
network_requires_substreams2exec --network without a key that covers Substreams or --product substreams.
command_missing2exec without a command after --.
unsupported_network2GraphOps does not serve Substreams for the network.
network_repeated2--network given more than once.
network_missing2--network without a value.
network_undetermined2No --network, and the manifest is not first or substreams info cannot read it.
webhook_url_missing2substreams sink webhook without the URL first.
sink_unsupported2substreams sink <kind> for a kind other than noop, protojson or webhook.
service_account_credential_invalid2GRAPHOPS_TOKEN starts with gsk_ but is not a well-formed service account API key.
query_key_not_supported2GRAPHOPS_TOKEN holds a query key (gqk_), which works only with data services.
organization_not_selected2No organization is configured and you are a member of several (or none).
organization_mismatch2The configured organization is not the service account's own organization ID.
coding_agent_not_found2agent-skills install found no coding agent; pass --agent.
skill_unknown2An agent skill name that GraphOps does not publish.
self_update_unsupported2self-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_in3No session and no GRAPHOPS_TOKEN, or GRAPHOPS_TOKEN is set but empty.
session_expired3The stored session expired and could not be refreshed, or the platform no longer accepts it.
session_invalid3The stored session is missing from the credential store or cannot be read.
credential_rejected3The platform did not accept the credential and sent no code of its own; for auth status --check, a GRAPHOPS_TOKEN it rejected.
unverified3auth status --check could not verify the credential, for example offline. Retryable when the cause is.
id_token_missing3The session has no ID token, or a refresh returned none.
sign_in_unavailable3Device sign-in is not available for this profile.
sign_in_denied3The sign-in was denied in the browser.
sign_in_expired3The sign-in code expired before it was approved.
sign_in_failed3The sign-in server refused or ended the sign-in, or returned a session without an expiry.
session_required3A person-only command run with a service account credential.
missing_key4No 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_product4The stored API key does not cover a data service exec --product names, or Substreams for the Substreams commands (125 under exec).
not_found5No Managed Subgraph, Endpoint Alias, API key or service account has that name or ID.
next_missing5The Managed Subgraph has no staged Next version.
next_changed5The staged Next version is not the one --expect-next names.
next_occupied5A different Next version is staged; pass --replace-next to replace it.
schema_incompatible5The new version's schema removes or changes query definitions; pass --accept-schema-changes.
managed_subgraph_deleting5The Managed Subgraph is being deleted.
managed_subgraph_suspended5The Managed Subgraph is suspended.
deployment_failed5The version subgraphs wait watches failed to index.
key_revoked5api-keys store of a revoked key.
no_data_services5api-keys create --store without products for an organization with no data services.
target_not_synced5The version an Endpoint Alias would serve is not synced and healthy; pass --force to change it anyway.
wait_timeout6subgraphs wait timed out.
launch_failed120The npm package could not start graphops: no build for this system, such as musl Linux, or the platform package is not installed.
tool_not_found127The wrapped tool, or the command exec runs, is not found.
cancelled130A person cancelled at a prompt: Ctrl-C or Esc, or No to a plan. Only at a terminal.

Next steps

Last updated