Troubleshooting

Troubleshooting

Common issues and their solutions.

CLI Issues

Installation Fails

Problem: CLI installation script fails.

Solutions:

  1. Check curl is installed:

    curl --version

  2. Check write permissions:

    # Try user-local installation
mkdir -p ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

  3. Manual installation: See CLI Installation for manual steps.

Command Not Found

Problem: onvera command not found after installation.

Solutions:

  1. Check installation location:

    which onvera
# or
ls -l ~/.local/bin/onvera

  2. Add to PATH: Add to ~/.bashrc or ~/.zshrc:

    export PATH="$HOME/.local/bin:$PATH"

    Then reload:

source ~/.bashrc


<a id="authentication-fails"></a>
### Authentication Fails

**Problem:** `onvera auth login` fails.

**Solutions:**

1. **Check you're logged in at [onvera.io](https://onvera.io)**
2. **Try API key authentication:**
   ```bash
   onvera auth login --token onv_sk_live_...
  1. Check API key is valid:
    • Verify key starts with onv_sk_live_
    • Check key hasn't been revoked
    • Ensure key hasn't expired

Deployment Fails

Problem: Deployment fails during creation.

Solutions:

  1. Check operation status:

    onvera ops get <operation_id>

  2. Check error message: The operation will include error details in the progress message.

  3. Common causes:

    • Resource limits exceeded
    • Network connectivity issues
    • Configuration errors

API Issues

401 Unauthorized

Problem: API returns 401 Unauthorized.

Solutions:

  1. Check API key is correct:

    echo $ONVERA_API_KEY

  2. Verify key format: Key must start with onv_sk_live_

  3. Check key hasn't been revoked: View keys in dashboard (opens in a new tab)

  4. Check key hasn't expired: Expired keys cannot be used

403 Forbidden

Problem: API returns 403 Forbidden.

Solutions:

  1. Check API key scopes: Your key may not have required permissions

  2. Verify organization membership: Ensure you're a member of the organization

  3. Check resource ownership: You can only access resources in your organization

429 Too Many Requests

Problem: API returns 429 Too Many Requests.

Solutions:

  1. Reduce request frequency: Don't poll operations more than every 2 seconds

  2. Implement exponential backoff: Wait longer between retries

  3. Check rate limits: See Rate Limits for limits

Deployment Issues

Deployment Stuck in Provisioning

Problem: Deployment stuck in provisioning status.

Solutions:

  1. Check operation status:

    onvera ops get <operation_id>

  2. Check deployment progress: Review the operation details for specific error messages

  3. Review operation details: Check the operation details for specific error messages and next steps

Deployment URL Not Working

Problem: Deployment URL returns error.

Solutions:

  1. Verify deployment is ready:

    onvera inspect <deployment_id>

    Status should be ready

  2. Check subdomain: Subdomain may still be propagating (can take 5-10 minutes)

  3. Try again later: DNS propagation can take time

Cannot Access Deployment

Problem: Cannot log in to deployed application.

Solutions:

  1. Check user provisioning: Users are automatically provisioned when added to organization

  2. Verify organization membership: Ensure you're a member of the organization

  3. Check deployment status: Deployment must be ready before access

Data Isolation