Find the cause of a failing graphops command and get back to work. Start with graphops doctor.
It checks whether a newer CLI version is available, your configuration, sign-in, organization,
credential store, your organization's API key (still active, and the variables graphops exec
sets), the graph and substreams tools, and whether the agent skills you installed with
graphops agent-skills install are up to date or GraphOps has published a new one. It prints one
line per check with a fix where there is one, and exits 1 when a check fails. An outdated CLI, or
a version check that can't reach the npm registry, is only a warning. As a service account, it
skips the device sign-in check, and suggests GRAPHOPS_API_KEY or graphops api-keys store for a
missing key.
To look up an exit code or an error code, see Reference.
graph not found or substreams not found
The CLI could not find the tool it runs. It uses the nearest node_modules/.bin/graph above the
current directory, then graph on your PATH, and substreams on your PATH.
- Run the command from your Subgraph project, or install Graph CLI in it.
- Install the Substreams CLI and check that
substreams --versionworks. - To use a binary elsewhere, set
GRAPHOPS_GRAPH_BINorGRAPHOPS_SUBSTREAMS_BINto its path.
graphops refuses an argument
graphops sets the GraphOps endpoint and credentials itself, so it refuses arguments that would
send them elsewhere: --node, --deploy-key and --watch for graph deploy, and --endpoint,
--plaintext, --insecure, --api-key-envvar and --api-token-envvar for Substreams.
- Remove the argument.
graphopsadds the endpoint for you. - To use another endpoint or Graph Node, run
graphorsubstreamsdirectly.
A value that starts with - is fine after a Substreams option that takes one, as in
--cursor -Xq9e2Ldw_kA.
Sign in again to continue
Creating a key needs a sign-in from the last 12 hours.
- Run
graphops auth login, then run the command again. - If
GRAPHOPS_TOKENis set, unset it first: it takes precedence over your sign-in. Rununset GRAPHOPS_TOKEN, orRemove-Item Env:GRAPHOPS_TOKENin PowerShell.
No API key is stored for the organization
Commands that use a key take the one stored for the organization you selected.
- Run
graphops api-keys create --store, or pipe an existing key tographops api-keys store. - Check the organization with
graphops auth status: a key stored for another organization is not used. - If you used GraphOps CLI 0.1, its per-product keys (
graphops rpc key,subgraphs key,substreams key) are no longer used.graphops api-keys forget --alldeletes them from your credential store; revoke them withgraphops api-keys revokeif you no longer need them.
Developer workflow covers storing and checking keys.
Secrets are stored in secrets.toml
No credential store was available, so the CLI used the file instead. On a desktop, sign in to a
session with the Keychain, the Secret Service or Credential Manager available. On a server or in
CI, set GRAPHOPS_TOKEN and GRAPHOPS_API_KEY instead, which are never stored.
Requests fail behind a proxy
The CLI sends its requests to GraphOps through the proxy named by the first of ALL_PROXY,
HTTPS_PROXY and HTTP_PROXY that is set; lower-case names work too. Hosts listed in NO_PROXY,
separated by commas, are reached without it. The Graph CLI and Substreams CLI that graphops runs
use their own proxy and certificate settings.
A certificate error usually means a proxy inspects TLS traffic with its own certificate authority. The CLI trusts what your operating system trusts: on macOS and Windows the operating system checks each certificate itself, and on Linux the CLI reads the system CA bundle and also trusts the public certificate authorities it includes.
- Ask your IT team to install the proxy's root certificate in the operating system's trust store: the Keychain on macOS, the Windows certificate store, or the system CA bundle on Linux.
- On Linux, to trust a certificate without installing it, set
SSL_CERT_FILEto a PEM file that contains it, orSSL_CERT_DIRto a directory of PEM files. The CLI then reads these instead of the system bundle, and still trusts the public certificate authorities.
PowerShell says running scripts is disabled
npm runs graphops in PowerShell through a script, which PowerShell's execution policy can block.
- Run
graphops.cmdinstead ofgraphops, with the same arguments. - Or allow local scripts for your account with
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
Next steps
Last updated
Scripts, CI and coding agents
Read the GraphOps CLI's JSON output in scripts, sign in a CI job as a service account, pin the CLI version, and let a coding agent use the CLI as you.
Reference
GraphOps CLI environment variables, exit codes and error codes, for scripts and process supervisors that act on how a command ended.