Troubleshooting

Authentication

Token expired

Symptom: CLI commands fail with "token expired" or "401 Unauthorized".

Solution: Refresh your authentication token:

riven auth login

This opens a browser window for re-authentication and stores a fresh token in ~/.config/riven/credentials.json.

Unauthorized on API calls

Symptom: RPC calls return "Unauthorized" even after logging in.

Solution: Verify your auth status and org membership:

# Check current auth state
riven auth status
 
# Verify the token is valid
riven auth token

If riven auth status shows a valid token but API calls still fail, confirm you are a member of the target organization. Org membership is managed through the platform UI or by an org admin.

CI authentication failing

Symptom: GitHub Actions or other CI pipelines fail with auth errors.

Solution: Set the RIVEN_TOKEN environment variable in your CI configuration. Do not use riven auth login in CI — it requires a browser.

env:
  RIVEN_TOKEN: ${{ secrets.RIVEN_TOKEN }}

Generate a CI token from the platform dashboard under Settings > API Keys.

Deployment

Image not found

Symptom: Deployment fails with "image not found" or "ErrImagePull".

Solution: Verify your ECR authentication is current:

AWS_PROFILE=your-profile aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  <account-id>.dkr.ecr.us-east-1.amazonaws.com

Then confirm the image exists in ECR:

aws ecr describe-images --repository-name <repo-name> --image-ids imageTag=<tag>

Rollout stuck

Symptom: A deployment appears to hang or is not making progress.

Solution: Check the rollout status and abort if needed:

# Check current rollout status
riven dev-center rollout status <service-name>
 
# If stuck, abort the rollout
riven dev-center rollout abort <service-name>

Common causes include failing health checks, resource limits being exceeded, or image pull errors. Check the pod logs for details.

Pod CrashLoopBackOff

Symptom: Pods restart repeatedly and never reach a ready state.

Solution: Inspect the logs from the most recent crash:

riven dev-center logs <service-name> --previous

Common causes:

• Missing environment variables or secrets
• Database connection failures
• Port conflicts
• OOM kills (check resource limits)

Health check failing

Symptom: Pods start but are killed by the liveness or readiness probe.

Solution: Verify the health endpoint returns a 200 response:

# Port-forward to the pod and test locally
kubectl port-forward pod/<pod-name> 8080:8080
curl http://localhost:8080/api/health

Ensure your service exposes a /api/health endpoint that returns HTTP 200 when the service is ready to accept traffic.

Proto / Codegen

Module not found after codegen

Symptom: TypeScript compilation fails with "Cannot find module" errors for generated proto code.

Solution: Pull the latest proto dependencies and regenerate:

# Update proto dependencies from the registry
riven proto pull --update
 
# Regenerate code
riven proto generate

If the issue persists, clear the local proto cache:

riven proto cache clean
riven proto pull --update
riven proto generate

Breaking change detected

Symptom: riven proto breaking or CI fails with breaking change errors.

Solution: Breaking changes in proto files require careful handling:

1. Review the breaking changes:

   bash

   riven proto breaking

2. Update all consumers of the changed proto package
3. Coordinate the rollout: deploy consumers first, then the provider
4. Re-publish the proto:

   bash

   riven proto publish

buf lint errors

Symptom: riven proto lint reports style violations.

Solution: Fix the proto files according to buf lint rules, then re-validate:

riven proto lint

Common lint issues:

• Missing package declaration
• Non-standard field naming (use snake_case)
• Missing comments on services and RPCs
• Incorrect package naming (should be riven.<domain>.v1)

Docker

Build failed

Symptom: docker build or riven publish fails during the build step.

Solution: Check the Dockerfile for common issues:

• Ensure multi-stage build is structured correctly
• Verify all COPY paths exist in the build context
• Check that yarn install or npm ci succeeds (dependency resolution errors)
• Ensure proto generation runs during the build step, not before

# Build locally to debug
docker build -t test-build .

Push permission denied

Symptom: docker push fails with "authorization failed" or "denied".

Solution: Re-authenticate with ECR:

AWS_PROFILE=your-profile aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  <account-id>.dkr.ecr.us-east-1.amazonaws.com

ECR login tokens expire after 12 hours. If you are in CI, ensure the login step runs before every push.

Getting More Help

If your issue is not covered here:

1. Check the service logs: riven dev-center logs <service-name>
2. Run diagnostics: riven doctor
3. File an issue in the relevant GitHub repository