Skip to content
vops

Troubleshooting

Start with the narrowest read-only check that crosses the failing boundary. Avoid changing firewall, credentials and application state at the same time; that makes the original cause harder to see.

Provider query fails

Terminal window
vops providers capabilities <provider>
vops config list
vops keyring status
vops providers plans <provider> --refresh
  • If static capabilities work but account data fails, focus on credentials.
  • If the vault is sealed and locked, unlock it from the terminal.
  • If only one provider fails, verify that provider’s variables and permissions.
  • A missing public catalog result is not evidence that provisioning credentials are invalid.

Host is unreachable

Terminal window
vops host show web-1
vops host status web-1
vops host ssh web-1 --print
vops host key status web-1

Check the recorded address, user, port and key before changing the remote SSH configuration. Verify the provider or host firewall still allows the SSH source.

If host add recorded an unreachable host, correct the access path and re-run the status probe; inventory registration itself did not damage the server.

Application will not start

Terminal window
vops app show my-api
vops app status my-api
vops app logs my-api --lines 300
vops app preflight web-1

Look for:

  • an image the host cannot pull;
  • a missing declared value;
  • a port already in use;
  • a failed health path;
  • insufficient disk or memory;
  • a runtime coexistence conflict reported by preflight.

Restart only after understanding whether the failure is transient:

Terminal window
vops app restart my-api

Restart leaves images, units and secrets in place.

Domain or TLS fails

Terminal window
vops ingress status web-1
vops app status my-api
vops deploy verify --app my-api
vops host firewall web-1

Confirm:

  1. the application is healthy before ingress;
  2. the hostname resolves to the host;
  3. ports 80 and 443 reach the host;
  4. no other process owns those ports;
  5. the certificate request used the intended production or staging endpoint.

Do not force DNS replacement until you know which existing record would be changed.

Backup fails

Terminal window
vops backup status web-1
vops backup snapshots web-1
vops backup run web-1

Verify the remote paths exist and the S3-compatible repository credentials are still valid. A restore should target a new directory first:

Terminal window
vops backup restore web-1 \
  --snapshot latest \
  --target /srv/restore-check \
  --yes

Inspect restored data before replacing a live path.

Dashboard reports a locked profile

The browser cannot prompt for the passphrase through an HTTP request:

Terminal window
vops keyring unlock

Retry the action, then vops keyring lock when the credential window is no longer needed.

Development agent is denied

Terminal window
vops agent status --project .
vops agent session list
vops agent session show <session-id>
vops agent approvals list --status pending
vops agent operations list --session <session-id>

Check expiry, pause/revoke state, target scope, environment, operation count and spend ceiling. A denial at the policy boundary should not be “fixed” by giving the agent raw provider or SSH credentials.

If the integration files are incomplete, repeat the idempotent setup and review the reported backups:

Terminal window
vops agent setup <client> --scope project --project .

Preserve evidence

Use --json when the failing command supports it, save the result locally and include:

  • installed vops version;
  • command and non-secret flags;
  • stable error code;
  • target provider or inventory name;
  • whether the failure happened in plan, apply or verify.

Never include raw tokens, private keys, application secret values or reusable agent session tokens.