Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.suga.app/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers common issues you might encounter when using Suga and how to resolve them. If you don’t find your issue here, contact support.

​
Quick Diagnosis

Before diving into specific issues, try these steps:
1

Check Deployment Status

Look at the deployment status in your canvas. Is it Pending, Running, or Failed?
2

Review Logs

Click on your service and check both deployment logs and runtime logs for error messages.
3

Verify Configuration

Double-check your environment variables, port numbers, and resource limits.
4

Check Metrics

Look at CPU and memory usage to see if you’re hitting resource limits.
5

Test Locally

If possible, test your Docker image locally with docker run to verify it works.

​
Deployment Issues

​
ImagePullBackOff

Problem: Deployment fails with ImagePullBackOff or ErrImagePull error.
Symptoms: Error message says “image not found” or “manifest unknown”Solutions:
  • Verify the image name is spelled correctly
  • Check that the tag exists in your registry
  • Try pulling the image locally: docker pull your-image:tag
  • Make sure you’re not using latest tag if you haven’t pushed it
Symptoms: Image exists but Suga can’t pull itSolutions:
  • Click on the service → Config tab → Image Source → “Add Registry Credentials”
  • Add your registry credentials (username, password, registry URL)
  • Make sure the registry URL is correct:
    • Docker Hub: docker.io or leave blank
    • GHCR: ghcr.io
    • GCR: gcr.io
    • ECR: [account-id].dkr.ecr.[region].amazonaws.com
  • Redeploy after adding credentials
Symptoms: Image pulls but won’t run, especially on Apple SiliconSolutions:
  • Rebuild your image for linux/amd64: 
    docker build --platform linux/amd64 -t your-image:tag .
  • Push the rebuilt image
  • Redeploy in Suga
Symptoms: Timeout or network errorsSolutions:
  • Verify the registry is online
  • Check if registry requires VPN or IP allowlisting
  • Try pulling from a different network
  • For self-hosted registries, ensure they’re publicly accessible or BYOC cluster has access

​
CrashLoopBackOff

Problem: Container starts but immediately crashes, then restarts repeatedly.
Symptoms: Logs show error messages or exceptionsSolutions:
  • Check logs for the actual error message
  • Common issues:
    • Missing environment variables
    • Database connection failures
    • Port binding errors
    • Missing dependencies
  • Test your image locally with same environment variables: 
    docker run -e VAR1=value1 -e VAR2=value2 your-image:tag
Symptoms: Logs show “command not found” or immediate exitSolutions:
  • Verify your Dockerfile’s CMD or ENTRYPOINT is correct
  • If overriding command in Suga, make sure it’s a valid command
  • Test locally: docker run your-image:tag
  • Common mistake: forgetting to copy the binary or script into the image
Symptoms: Error about port already in use or can’t bind to portSolutions:
  • Make sure your application binds to 0.0.0.0, not localhost: 
    // Good
app.listen(3000, '0.0.0.0');

// Bad
app.listen(3000, 'localhost');
  • Verify the port in Public Networking config matches your app’s listening port
  • Don’t use privileged ports (1-1024) unless necessary
Symptoms: Errors about missing libraries, modules, or filesSolutions:
  • Verify all dependencies are installed in your Dockerfile
  • For Node.js: RUN npm install or RUN npm ci
  • For Python: RUN pip install -r requirements.txt
  • For compiled languages: Include runtime dependencies
  • Test your image locally to ensure everything is included
Symptoms: OOMKilled (Out of Memory) in logsSolutions:
  • Increase memory allocation in Config → Resources
  • Start with at least 512 MiB, increase to 1 GiB or more if needed
  • Check metrics to see actual memory usage
  • Optimize your application’s memory usage

​
Deployment Stuck in Pending

Problem: Deployment remains in “Pending” state and doesn’t progress.
Symptoms: Deployment pending for several minutesSolutions:
  • Your plan may be at resource limits
  • Check total CPU/memory across all services in environment
  • Delete unused services or environments to free resources
  • Upgrade plan for more resources
Symptoms: Service with volume stuck in pendingSolutions:
  • Verify volume is connected properly on canvas
  • Check that mount path is valid (starts with /)
  • Ensure service has only 1 replica (volumes don’t work with >1)
  • Try disconnecting and reconnecting the volume
Symptoms: Large Docker image, pending for a whileSolutions:
  • Be patient - large images (>1 GB) take time to pull
  • Check logs for “Pulling image” messages
  • Consider optimizing image size:
    • Use multi-stage builds
    • Use Alpine-based images
    • Remove unnecessary files
    • Use .dockerignore

​
Networking Issues

​
Can’t Access Public HTTPS Endpoint

Problem: Deployment succeeded but can’t reach the service at the Suga URL.
Symptoms: Connection refused or 502 Bad GatewaySolutions:
  • Verify the port in Public Networking config matches your app’s listening port
  • Check logs: look for “Server listening on port X”
  • Common ports: 3000 (Node.js), 8000 (Python), 8080 (Java/Go)
  • Update port in Config tab → Public Network section
  • Redeploy after changing port
Symptoms: App starts successfully but not accessibleSolutions:
  • Ensure your app binds to 0.0.0.0 (all interfaces), not localhost: 
    // Node.js/Express
app.listen(3000, '0.0.0.0');

    # Python/FastAPI
uvicorn.run(app, host="0.0.0.0", port=8000)

    // Go
http.ListenAndServe("0.0.0.0:8080", nil)
  • Rebuild and redeploy with the fix
Symptoms: Was accessible briefly, now notSolutions:
  • Check runtime logs for errors
  • Look for crashes, exceptions, or OOM (Out of Memory) kills
  • Check metrics for resource usage spikes
  • Increase resources if hitting limits

​
Can’t Connect to Other Services

Problem: Service can’t connect to database or other services in same environment.
Symptoms: DNS errors, connection refused, host not foundSolutions:
  • Use the service name as hostname, not the full Suga URL
  • Format: service-name:port
  • Example: postgres:5432, not a public URL like def456ghi.suga.app
  • Check service name on canvas (may be different from display name)
  • Use lowercase and hyphens for multi-word names
Symptoms: Connection refused on specific portSolutions:
  • Verify the target service’s port
  • Common ports:
    • PostgreSQL: 5432
    • MySQL/MariaDB: 3306
    • Redis: 6379
    • MongoDB: 27017
  • Check the target service’s logs to see what port it’s listening on
Symptoms: Connection refused or timeout when connectingSolutions:
  • Check if target service is fully running and healthy
  • Look at deployment status on canvas
  • Database services may take 30-60 seconds to fully start
  • Implement retry logic in your application
Symptoms: Persistent connection timeoutsSolutions:
  • Private networking should work automatically within same environment
  • Verify both services are in the same environment
  • Check logs for network-related errors
  • Contact support if issue persists

​
Custom Domain Not Working

Problem: Custom domain doesn’t resolve to your application.
Symptoms: Domain doesn’t resolve or goes to wrong placeSolutions:
  • DNS propagation can take 1-48 hours
  • Check DNS with: dig your-domain.com or nslookup your-domain.com
  • Verify CNAME record points to your Suga domain
  • Correct format:
    • Type: CNAME
    • Name: www (or @)
    • Value: your-service-env-project.suga.app
  • Lower TTL (300-600 seconds) for faster updates
Symptoms: Domain resolves to wrong place or not at allSolutions:
  • Log into your DNS provider (Cloudflare, Namecheap, GoDaddy, etc.)
  • Verify CNAME record exists and is correct
  • Should point to your auto-generated Suga domain
  • Don’t include https:// in CNAME value
  • Don’t add trailing dot unless required by provider
Symptoms: “Not Secure” warning or certificate errorSolutions:
  • Certificate issuance can take 5-15 minutes
  • Verify DNS is correctly pointing to Suga
  • Clear browser cache and try again
  • Check domain in incognito/private window
  • Contact support if certificate doesn’t issue within 1 hour
Symptoms: Root domain (example.com) doesn’t work, only www worksSolutions:
  • Apex domains require ANAME or ALIAS records (not all DNS providers support)
  • Options:
    1. Use www subdomain instead
    2. Use DNS provider that supports ANAME/ALIAS (Cloudflare, DNSimple, DNS Made Easy)
    3. Set up redirect from apex to www
  • CNAME records cannot be used for apex domains (DNS limitation)

​
Resource Issues

​
Out of Memory (OOMKilled)

Problem: Container crashes with OOMKilled in logs.
Symptoms: Application crashes under load or during specific operationsSolutions:
  • Increase memory in Config → Resources
  • Start with doubling current limit (512 MiB → 1 GiB → 2 GiB)
  • Monitor metrics after increase to see actual usage
  • Some applications need more memory during startup
  • Consider memory requirements of your framework/runtime
Symptoms: Memory usage grows over time, eventually crashesSolutions:
  • Profile your application for memory leaks
  • Look for:
    • Unclosed database connections
    • Event listeners not removed
    • Growing caches without limits
    • Large objects kept in memory
  • Implement connection pooling with max limits
  • Add memory limits to in-memory caches
Symptoms: OOMKilled during specific operations (file uploads, exports, etc.)Solutions:
  • Stream large files instead of loading entirely into memory
  • Process data in chunks/batches
  • Use temporary files for large operations
  • Increase memory limit for data-intensive operations
  • Consider offloading heavy processing to separate service

​
High CPU Usage

Problem: CPU usage constantly near 100% or application is slow.
Symptoms: Metrics show CPU usage at or near limitSolutions:
  • Increase CPU in Config → Resources
  • Monitor metrics after increase
  • Consider horizontal scaling (replicas) for web apps
Symptoms: CPU high even with low trafficSolutions:
  • Profile your application to find bottlenecks
  • Common issues:
    • Synchronous blocking operations
    • Inefficient algorithms
    • Missing database indexes
    • N+1 query problems
    • Not using caching
  • Optimize hot code paths
  • Add caching for expensive operations
Symptoms: CPU usage correlates with request volumeSolutions:
  • Scale horizontally by increasing replicas
  • Config tab → Replicas: 2, 3, or more
  • Load balancing happens automatically
  • Add caching (Redis) for frequently accessed data
  • Optimize database queries
  • Consider CDN for static assets

​
Disk Space Issues

Problem: Application can’t write files or “disk full” errors.
Symptoms: Can’t persist files, data lost on restartSolutions:
  • Services have small ephemeral storage (not persistent)
  • Create a Volume and add it to the canvas
  • Connect volume to your service
  • Set mount path (e.g., /data, /app/uploads)
  • Update your app to write to the mount path
  • Redeploy
Symptoms: “No space left on device” errorSolutions:
  • Check disk usage in logs: df -h /data
  • Delete old or unnecessary files
  • Implement log rotation
  • Clean up temporary files
  • Volume size limits vary by plan. See Plan Limits for tier caps
Symptoms: Files seem to write but disappear on restartSolutions:
  • Verify you’re writing to the mounted volume path
  • Example: If volume mounted at /data, write to /data/file.txt
  • Don’t write to root filesystem locations unless on volume
  • Check volume connection on canvas
  • Verify mount path in Config → Volumes

​
Function-Specific Issues

​
Function Timeout

Problem: Deno function times out before completing.
Symptoms: Function timeout error in logsSolutions:
  • Functions have limited execution time
  • Optimize slow operations:
    • Use database indexes
    • Limit query results
    • Cache expensive computations
    • Process data in smaller chunks
  • For long-running tasks, use a Container service instead
Symptoms: Timeout when calling external servicesSolutions:
  • Set shorter timeouts on external HTTP calls
  • Implement retry logic with exponential backoff
  • Cache results when possible
  • Consider async processing for slow operations

​
AI Assistant Not Working

Problem: AI assistant for Deno functions not responding or giving errors.
Symptoms: AI assistant unavailable or disabledSolutions:
  • AI assistant is a Pro feature
  • Upgrade to Pro plan ($20/user/month)
  • Check subscription in Org Settings → Billing
Symptoms: Error message about quota or limit reachedSolutions:
  • Pro plan includes 500K tokens/user/month
  • Check usage in Org Settings → Billing
  • Wait for next billing cycle for quota reset
  • Contact sales for higher limits (Enterprise)
Symptoms: Error about input being too longSolutions:
  • AI has context limits
  • Simplify your question
  • Break large functions into smaller pieces
  • Focus on specific problematic sections

​
Volume Issues

​
Can’t Mount Volume

Problem: Volume won’t connect to service or deployment fails with volume error.
Symptoms: Error about replicas when mounting volumeSolutions:
  • Volumes cannot be mounted to services with >1 replica
  • Reduce replicas to 1 in Config tab → Replicas
  • This is a fundamental limitation (prevents data corruption)
  • For scalable apps needing storage, use:
    • External database service
    • Object storage (S3-compatible)
    • Shared filesystem (coming soon)
Symptoms: Volume in use or locked errorSolutions:
  • Each volume can only be mounted to one service
  • Disconnect volume from other service first
  • Create separate volumes for different services
  • Check canvas for existing volume connections
Symptoms: Error about mount path during deploymentSolutions:
  • Mount path must be absolute (start with /)
  • Don’t use root directories: /, /etc, /usr, /bin
  • Use subdirectories: /data, /app/storage, /var/lib/postgresql/data
  • Path must not conflict with application directories

​
Volume Data Lost

Problem: Data in volume disappeared or was reset.
Symptoms: All data gone, volume shows as newSolutions:
  • Deleting a volume permanently deletes data (no recovery)
  • Check deployment history to see if volume was deleted
  • Restore from backups if available
  • Implement regular backup strategy going forward
Symptoms: Data disappears after restartSolutions:
  • Verify application writes to correct mount path
  • Check logs for actual file paths being used
  • Data written outside mount path is ephemeral (lost on restart)
  • Update application to use mounted volume path
Symptoms: Volume exists but no data visibleSolutions:
  • Check volume is connected on canvas
  • Verify mount path in service config
  • Check logs for volume mounting errors
  • Redeploy to remount volume

​
Account and Billing Issues

​
Can’t Log In

Problem: Unable to access Suga dashboard.
Symptoms: “Invalid email or password” errorSolutions:
  • Verify email address is correct
  • Try password reset: Click “Forgot Password”
  • Check caps lock is off
  • Try different browser or incognito mode
  • Clear browser cache and cookies
Symptoms: “No account found” errorSolutions:
  • Verify you signed up (check email for confirmation)
  • Try signing up again if no confirmation received
  • Check spam folder for activation email
  • Contact support at support@suga.app
Symptoms: SAML or SSO errorsSolutions:
  • Contact your organization admin
  • Verify SSO configuration in organization settings
  • Try using email/password instead (if enabled)
  • Contact support for SSO troubleshooting

​
Billing or Plan Issues

Problem: Issues with subscription, billing, or plan limits.
Symptoms: Can’t create more projects/environments, resource allocation failsSolutions:
  • Review plan limits in Org Settings → Billing
  • Delete unused resources to free up quota
  • Upgrade plan for higher limits
Symptoms: Billing error, services suspendedSolutions:
  • Check payment method in Org Settings → Billing
  • Verify card is not expired
  • Check sufficient funds available
  • Update payment method
  • Contact support if issue persists: billing@suga.app
Symptoms: Want to switch from Pro to FreeSolutions:
  • First reduce resources to fit Free plan limits:
    • Max 1 project
    • Max 1 environment
    • Delete extra resources
  • Then request downgrade in Org Settings → Billing
  • Or contact billing@suga.app
Symptoms: Need billing documentationSolutions:
  • Go to Org Settings → Billing → Invoices
  • Download PDF invoices for past months
  • Invoices include all charges and payment details
  • For custom invoices or tax forms, email billing@suga.app

​
Getting More Help

If you can’t find a solution here:

Discord Community

Get help from community and team

Email Support

Contact support@suga.app

GitHub Issues

Report bugs and request features

​
What to Include When Asking for Help

To get faster support, include:
  • Project name and organization name
  • Environment name (production, staging, etc.)
  • Service name affected
  • Complete error messages from logs
  • Steps to reproduce the issue
  • When it started happening
  • What you’ve already tried
  • Screenshots if applicable
The more details you provide, the faster we can help resolve your issue.

​
Debugging Checklist

When troubleshooting, work through this checklist:
1

Check Deployment Status

Is the service Running, Pending, or Failed? Look at the canvas status.
2

Review Deployment Logs

Click service → Logs → Deployment. Look for errors during startup.
3

Review Runtime Logs

Click service → Logs → Runtime. Look for application errors.
4

Verify Configuration

Check all settings in Config tab: env vars, ports, resources, networking.
5

Check Metrics

Click service → Metrics. Look for resource exhaustion (CPU/memory at limits).
6

Test Connections

Verify networking: can you reach HTTPS endpoint? Can services connect to each other?
7

Review Recent Changes

Did the issue start after a deployment? Check deployment history and consider rollback.
8

Test Locally

Pull and run your Docker image locally with same config to isolate the issue.
Start with the logs - they usually contain the exact error message that points to the solution.