Skip to content

Troubleshooting

Fix common GraphOps CLI problems, from missing tools and refused arguments to proxies, PowerShell policies and missing API keys.

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.

  1. Run the command from your Subgraph project, or install Graph CLI in it.
  2. Install the Substreams CLI and check that substreams --version works.
  3. To use a binary elsewhere, set GRAPHOPS_GRAPH_BIN or GRAPHOPS_SUBSTREAMS_BIN to 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.

  1. Remove the argument. graphops adds the endpoint for you.
  2. To use another endpoint or Graph Node, run graph or substreams directly.

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.

  1. Run graphops auth login, then run the command again.
  2. If GRAPHOPS_TOKEN is set, unset it first: it takes precedence over your sign-in. Run unset GRAPHOPS_TOKEN, or Remove-Item Env:GRAPHOPS_TOKEN in PowerShell.

No API key is stored for the organization

Commands that use a key take the one stored for the organization you selected.

  1. Run graphops api-keys create --store, or pipe an existing key to graphops api-keys store.
  2. Check the organization with graphops auth status: a key stored for another organization is not used.
  3. 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 --all deletes them from your credential store; revoke them with graphops api-keys revoke if 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.

  1. 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.
  2. On Linux, to trust a certificate without installing it, set SSL_CERT_FILE to a PEM file that contains it, or SSL_CERT_DIR to 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.

  1. Run graphops.cmd instead of graphops, with the same arguments.
  2. Or allow local scripts for your account with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Next steps

Last updated