Skip to main content
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 open the Logs tab. It shows everything your service wrote to stdout and stderr, including startup errors.
3

Verify Configuration

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

Check Resource Usage

Open the service’s Status tab and 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:
  • Select the service and open its Config tab, then expand Registry credentials
  • Add your username and password or access token
  • Make sure the image URI includes the registry host, since Suga reads the host from it:
    • Docker Hub: no prefix needed, e.g. myuser/myapp:v1
    • GHCR: ghcr.io/myuser/myapp:v1
    • GCR: gcr.io/my-project/myapp:v1
    • ECR: [account-id].dkr.ecr.[region].amazonaws.com/myapp:v1
  • Apply after adding credentials
Symptoms: Image pulls but won’t run, especially on Apple SiliconSolutions:
  • Rebuild your image for linux/amd64:
  • 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:
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:
  • Verify the port in the Public Networking section 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
  • Check the Status tab to see actual memory usage, then set the limit above the peak
  • On the Free plan memory is capped at 256 MiB, so a service that needs more has to move to a paid plan
  • 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 the Public Networking section 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 the port in Config tab → Public Networking
  • Apply after changing the port
Symptoms: App starts successfully but not accessibleSolutions:
  • Ensure your app binds to 0.0.0.0 (all interfaces), not localhost:
  • 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 the Status tab for resource usage spikes
  • Increase resources if hitting limits

​
Long-Lived Connection Drops

Problem: WebSocket, Server-Sent Events stream, or database connection drops every few minutes.
Symptoms: Connection closes after ~5 minutes of inactivity (HTTPS) or ~15 minutes (TCP Proxy)Solutions:
  • WebSockets: send a ping frame every 1–2 minutes
  • SSE: emit : keepalive\n\n or a heartbeat event every 1–2 minutes
  • TCP Proxy clients: enable SO_KEEPALIVE or a protocol-level keepalive (e.g. PostgreSQL keepalives_idle)
  • See Connection Timeouts for full details
Symptoms: Connection closes without warning, no idle patternSolutions:
  • Suga Cloud closes connections whose peer has gone away (network partition, crashed client) within ~2.5 minutes
  • Have the client reconnect with backoff
  • Check client-side network conditions and crash logs

​
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 k3f9x2mq7p1a-production-a1b2c3d4.us-central1.suga.run
  • The hostname is set in Config tab → Private Networking → Hostname. It is a DNS-safe version of the display name, so it may differ from what you see on the canvas
  • 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: the subdomain you’re adding, e.g. www
    • Value: the exact target Suga showed you when you added the domain. It contains a hash, so you cannot type it from memory
  • 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 the target Suga gave you, not to your generated URL
  • 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)
  • Watch the Status tab after the 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: The Status tab shows CPU usage at or near the limitSolutions:
  • Increase CPU in Config → Resources
  • Watch the Status tab after the 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 the mount path in the Volumes tab

​
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

​
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 /). That is the only rule Suga enforces
  • Use a dedicated subdirectory: /data, /app/storage, /var/lib/postgresql/data
  • Mounting over a directory the image already uses, such as /etc or /usr, is allowed but hides the image’s own files there and usually breaks the container. Pick a path your image does not need

​
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 the Billing page in the left sidebar
  • Delete unused resources to free up quota
  • Upgrade plan for higher limits
Symptoms: Billing error, services suspendedSolutions:
  • Check payment method in the Billing page in the left sidebar
  • Verify card is not expired
  • Check sufficient funds available
  • Update payment method
  • Contact support if issue persists: support@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 the Billing page in the left sidebar
  • Or contact support@suga.app
Symptoms: Need billing documentationSolutions:
  • Go to the Billing page in the left sidebar
  • Download PDF invoices for past months
  • Invoices include all charges and payment details
  • For custom invoices or tax forms, email support@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 Logs

Click service → Logs. This is everything your service wrote to stdout and stderr, including startup. Filter by level to find errors quickly, or select Open in Logs explorer for the full view.
3

Verify Configuration

Check all settings in the Config and Env Vars tabs: variables, ports, resources, networking.
4

Check Resource Usage

Click service → Status. Look for resource exhaustion (CPU or memory at limits).
5

Test Connections

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

Review Recent Changes

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

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.