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.

Search

Search returns no results

Symptom: riven search returns empty results even though pages exist.

Solution: The Meilisearch index may need to be rebuilt. This can happen after a service restart or if the search-service was deployed after pages were created.

Contact a platform admin to trigger a reindex, or check the search-service logs:

riven dev-center logs search-service

Search results are stale

Symptom: Recently created or updated pages do not appear in search results.

Solution: Search indexing is asynchronous. New pages typically appear within 30 seconds. If results remain stale after a few minutes, check the search-service health:

riven dev-center rollout status search-service

Getting More Help

If your issue is not covered here:

1. Search the Internal Docs for related troubleshooting pages
2. Check the service logs: riven dev-center logs <service-name>
3. Run diagnostics: riven doctor
4. File an issue in the relevant GitHub repository