Railway

Deploy and troubleshoot Railway projects. Focused on diagnosing deployment failures and build issues.

Troubleshooting Decision Tree

When a deployment fails or behaves unexpectedly, follow this sequence:

1. railway status --json     → Check deployment status (FAILED/SUCCESS/etc.)
2. railway logs --build      → Check build-phase errors
3. railway logs --deployment → Check runtime errors  
4. railway logs              → Stream live application logs
5. railway ssh               → Direct container access for debugging
6. railway open              → Dashboard fallback when CLI insufficient

Quick Diagnostics

Check current project/service context:

railway status

Get detailed deployment state as JSON (includes status, config, volumes, domains):

railway status --json

Parse deployment status programmatically:

railway status --json | jq '.services.edges[0].node.serviceInstances.edges[0].node.latestDeployment.status'

Viewing Logs

Build logs (compilation, dependency install, Dockerfile steps):

railway logs --build

Deployment logs (startup, runtime initialization):

railway logs --deployment

Application logs (live stream from running service):

railway logs

JSON format for parsing:

railway logs --json | jq -r '.message'

Specific service (when project has multiple services):

railway logs -s <service-name> --build
railway logs -s <service-name>

Common Failure Patterns

"No deployments found"

The deployment may have failed before logs were created. Check:

railway status --json | jq '.services.edges[].node.serviceInstances.edges[].node.latestDeployment'

Build failures

# Check build logs
railway logs --build

# Common causes:
# - Missing dependencies in package.json/requirements.txt
# - Dockerfile errors
# - Build command failures

Runtime crashes

# Check deployment logs for startup errors
railway logs --deployment

# Then check application logs
railway logs

# Common causes:
# - Missing environment variables
# - Port binding issues (use PORT env var)
# - Database connection failures

Service not accessible

# Check domain configuration
railway status --json | jq '.services.edges[].node.serviceInstances.edges[].node.domains'

# Verify service is running
railway status --json | jq '.services.edges[].node.serviceInstances.edges[].node.latestDeployment.status'

Deploying

Deploy current directory:

railway up

Deploy without streaming logs (CI/scripts):

railway up --detach

Deploy to specific service:

railway up -s <service-name>

Redeploy latest (after config change):

railway redeploy -y

Rollback (remove most recent deployment):

railway down

Environment Variables

View all variables:

railway variables

View as JSON:

railway variables --json

Set a variable:

railway variables --set "KEY=value"

Set multiple without triggering redeploy:

railway variables --set "A=1" --set "B=2" --skip-deploys
railway redeploy -y  # Deploy once after all changes

Direct Container Access

SSH into running service:

railway ssh

Connect to database shell:

railway connect           # Interactive selection
railway connect postgres  # Direct psql
railway connect redis     # Direct redis-cli

Local Development

Run command with Railway environment variables:

railway run npm start
railway run python app.py

Open shell with Railway vars loaded:

railway shell
echo $DATABASE_URL  # Railway vars available

Project Management

Link directory to project:

railway link
railway link <project-id>

Switch environment:

railway environment production
railway environment staging

Create new environment:

railway env new staging

Open dashboard in browser:

railway open

Key JSON Paths

When parsing railway status --json:

Path	Description
.services.edges[].node.name	Service names
.services.edges[].node.serviceInstances.edges[].node.latestDeployment.status	Deployment status
.services.edges[].node.serviceInstances.edges[].node.latestDeployment.meta	Build config, commands
.services.edges[].node.serviceInstances.edges[].node.domains	Domain configuration
.volumes.edges[].node.volumeInstances.edges[].node	Volume mounts, sizes
.environments.edges[].node.name	Environment names

Railway Environment Variables

These are automatically available in Railway deployments:

Variable	Description
PORT	Port to bind to
RAILWAY_ENVIRONMENT	Current environment name
RAILWAY_SERVICE_NAME	Service name
RAILWAY_PUBLIC_DOMAIN	Public domain URL
RAILWAY_PRIVATE_DOMAIN	Internal domain (service-to-service)
DATABASE_URL	Database connection string (if database provisioned)