Troubleshooting

Common issues and solutions for Rise.

Build Issues

Buildpack: CA Certificate Verification Errors

Symptoms:

===> ANALYZING
[analyzer] ERROR: failed to initialize analyzer: validating registry read access to <registry>
ERROR: failed to build: executing lifecycle: failed with status code: 1

Cause: Pack lifecycle container cannot verify SSL certificates when accessing the registry.

Solution:

export SSL_CERT_FILE=/path/to/your/ca-cert.crt
rise deployment create my-app

Rise CLI automatically injects the certificate into the pack lifecycle container.

Manual workaround (pack CLI directly):

pack build my-image \
  --builder paketobuildpacks/builder-jammy-base \
  --env SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt \
  --volume $SSL_CERT_FILE:/etc/ssl/certs/ca-certificates.crt:ro

Still failing?

1. Verify certificate format: openssl x509 -in /path/to/ca-cert.crt -text -noout
2. Use verbose logging: rise deployment create my-app --verbose
3. Test registry access: curl --cacert /path/to/ca-cert.crt https://your-registry.example.com/v2/

Railpack: BuildKit Experimental Feature Error

Symptom:

ERROR: failed to build: failed to solve: requested experimental feature mergeop has been disabled on the build server: only enabled with containerd image store backend

Cause: Docker Desktop’s default builder doesn’t support experimental features needed by Railpack.

Solution:

docker buildx create --use

See Building Images for more details on SSL certificates and managed BuildKit daemon.

Authentication Issues

“Failed to start local callback server”

Cause: Ports 8765, 8766, and 8767 are all in use.

Solution:

1. Close applications using these ports
2. Use device flow (if using a compatible OAuth2 provider): rise login --device

“Code exchange failed”

Common causes:

1. Backend is not running
2. Dex is not configured properly
3. Network connectivity issues

Check:

# Backend logs
docker-compose logs rise-backend

# Dex logs
docker-compose logs dex

Token Expired

Symptom: 401 Unauthorized on API requests.

Solution:

rise login

Tokens expire after 1 hour (default).

Service Account Issues

“The ‘aud’ claim is required”

Add --claim aud=<unique-value>:

rise sa create my-project \
  --issuer https://gitlab.com \
  --claim aud=rise-project-my-project \
  --claim project_path=myorg/myrepo

“At least one claim in addition to ‘aud’ is required”

Add authorization claims:

rise sa create my-project \
  --issuer https://gitlab.com \
  --claim aud=rise-project-my-project \
  --claim project_path=myorg/myrepo  # Required

“Multiple service accounts matched this token”

Cause: Ambiguous claim configuration.

Solution: Make claims unique:

# Unprotected branches
rise sa create dev --claim aud=rise-project-app-dev \
  --claim project_path=myorg/app --claim ref_protected=false

# Protected branches
rise sa create prod --claim aud=rise-project-app-prod \
  --claim project_path=myorg/app --claim ref_protected=true

“No service account matched the token claims”

Debug steps:

1. Check token claims (CI/CD systems usually log them)
2. Verify exact match (case-sensitive)
3. Check issuer URL (must match exactly, no trailing slash)
4. Ensure ALL service account claims are present in the token

“403 Forbidden” (Service Account)

Service accounts can only deploy, not manage projects. Use a regular user account for project operations.

Database Issues

“Connection refused” to PostgreSQL

Check if running:

docker-compose ps postgres
docker-compose logs postgres

Restart:

docker-compose restart postgres

Verify health:

docker-compose exec postgres pg_isready -U rise

Registry Issues

“Access Denied” when pushing (ECR)

Causes:

1. Controller role can’t assume push role
2. Push role permissions insufficient
3. Repository doesn’t exist with correct prefix
4. STS session policy scope incorrect

Debug:

# Check IAM role trust policy
aws iam get-role --role-name rise-backend-ecr-push

# Check repository exists
aws ecr describe-repositories --repository-names rise/my-app

“Connection refused” to registry (Docker)

Check if running:

docker-compose ps registry
docker-compose logs registry

Restart:

docker-compose restart registry

Images not persisting (Docker)

Check volume:

docker volume ls | grep registry

Warning: docker-compose down -v removes volumes and deletes all images!

Development Environment Issues

“Address already in use” on port 3000

Find process:

lsof -i :3000

Solution: Kill the process or change port in config/local.toml

Docker Compose services won’t start

Check logs:

docker-compose logs

Reset (deletes data):

docker-compose down -v
mise backend:deps

Getting Help

• Check logs: docker-compose logs <service>
• Verbose CLI output: rise <command> --verbose
• Backend logs: RUST_LOG=debug cargo run --bin rise -- backend server
• Report issues: https://github.com/anthropics/rise/issues