When deploying containerized applications, configuration mistakes, registry limitations, or server resource bottlenecks can occasionally cause a deployment to fail.

When a stack encounters an issue, RunCloud provides diagnostic information at two locations:

  1. Deployments Tab (Stack > Deployments): Lists all deployment attempts, elapsed durations, and operational statuses (Running or Failed). Clicking any deployment opens the full generated Docker Swarm configuration manifest and highlights the specific reason for the failure.
  2. Container Logs Tab (Stack > Containers > [Container Name] > Logs): Displays the raw stdout/stderr application output stream in real time.
container lgos

Different Error Codes and Solutions

1. Image Cannot Be Found or Downloaded

This error occurs when the Docker engine on your server attempts to pull the container image from the registry, but the image repository or tag could not be found.

Common Causes:

  • An error in the image repository name or version tag.
  • The requested tag has been deprecated or deleted from the registry.
  • The image repository is private, but no credentials were provided.

Step-by-Step Resolution:

  1. Navigate to Stacks and select your failed stack.
  2. Under the “Containers” menu, click on Settings for the affected container.
  3. Verify that the image repository name and version tag are spelled correctly.
  4. Open your web browser and search the repository on Docker Hub or your registry web console to confirm that the image tag actually exists.
  5. If the image is stored in a private repository, ensure you have saved valid credentials under Settings > Registry Credentials.
  6. Return to your stack and click Deploy Stacks to retry the deployment.

2. Registry Pull Rate Limit Exceeded

This happens when the container registry is temporarily rejecting pull requests from your server because your server’s IP address has exceeded the provider’s download quota.

Common Causes:

Docker Hub enforces strict download limits on anonymous users (typically 100 pulls every 6 hours per IP address). Public cloud server IP addresses frequently share anonymous quotas with neighboring machines.

Step-by-Step Resolution:

  1. Navigate to Settings > Registry Credentials in your RunCloud dashboard.
  2. Click Add Registry Credential.
  3. Select “Docker Hub” from the dropdown menu.
  4. Enter your Docker Hub username and personal access token. Adding authenticated credentials increases your download quota.
  5. Click Save Credential.
  6. Return to Stacks, open your stack, and click Deploy Stacks.

3. Authentication Failed

This error means that RunCloud attempted to authenticate with your private container registry, but the registry rejected the credentials.

Common Causes:

  • The password or personal access token has expired.
  • The access token lacks the required read permissions (read:packages or pull rights).
  • The username was typed incorrectly.

Step-by-Step Resolution:

  1. Log in to your registry provider dashboard (such as GitHub, Docker Hub, or AWS).
  2. Generate a new personal access token with package read permissions.
  3. In your RunCloud dashboard, navigate to Settings > Registry Credentials.
  4. Locate the credential entry for that registry and click the edit icon.
  5. Paste your new access token or password into the “Password / Token” field.
  6. Click Save Credential.
  7. Return to your stack and click Deploy Stacks.

4. Host Engine Initialization Failure

The Docker daemon running on your host server encountered an unexpected error while initializing container resources.

Common Causes:

  • A temporary communication lock or process hang in the local Docker daemon service.
  • A corrupted local image cache layer on the host.

Step-by-Step Resolution:

  1. Verify that your container image runs properly in a local testing environment.
  2. In the stack’s Settings tab, click Sync State to re-poll the host engine.
  3. Return to the Stack Overview and click Deploy Stacks to prompt RunCloud to re-trigger the daemon sequence.
  4. If the error persists, navigate to Server > Services in your RunCloud dashboard.
  5. Locate the “Docker” service entry and click Restart.
  6. Return to your stack and redeploy.

5. Orchestration Convergence Failure

This error occurs when the Docker Swarm orchestration engine cannot schedule or converge the container tasks onto the server.

Common Causes:

  • The combined CPU or RAM requests across your containers exceed the physical resources available on your server.
  • The server has reached its maximum replica capacity.

Step-by-Step Resolution:

  1. Open your stack configuration on the Stacks page.
  2. Click on the container that failed to converge.
  3. Under the container sub-menu, open Settings.
  4. Lower the allocated CPU cores and memory limits so they fit comfortably within your server’s free capacity.
  5. If you configured container replicas, reduce the replica count to 1.
  6. Click Deploy Stacks to apply your adjusted resource allocations.

6. SSL / TLS Certificate Validation Failed

This means that RunCloud was unable to obtain an automated SSL certificate from Let’s Encrypt for your domain.

Common Causes:

  • The domain DNS A record does not point to your server IP address.
  • Newly modified DNS records have not finished global propagation.
  • A web application firewall (such as Cloudflare with proxy mode enabled) is blocking the Let’s Encrypt HTTP-01 challenge.

Step-by-Step Resolution:

  1. Log in to your DNS management provider (such as Cloudflare, Namecheap, or Route 53).
  2. Look for the A record matching your domain or subdomain.
  3. Verify that the IP address in the A record exactly matches your RunCloud server IP address.
  4. If you use Cloudflare, temporarily set the proxy status to “DNS Only” (grey cloud icon) so the ACME verification challenge can reach your server directly.
  5. Wait a few minutes for DNS propagation.
  6. Return to your stack in RunCloud, navigate to Containers > Domain & SSL, and click Re-Issue SSL.

7. Port Collision or Unreachable Network

RunCloud could not bind the container port because the designated host port is already in use by another application or container on your server.

Common Causes:

Another web application, stack, or system service is already listening on the requested port.

Step-by-Step Resolution:

  1. Open your stack on the Stacks page.
  2. Look under the container sub-menu and click on Ports.
  3. Identify the conflicting port binding and change the host port assignment to an unused port number (for example, change port 8080 to 8085).
  4. Click Deploy Stacks to rebind the network interface.

8. health_check: Application Readiness Check Failed

This happens when the container started successfully, but the application inside failed to respond to internal health checks or readiness probes.

Common Causes:

  • The application crashed immediately after boot due to missing or invalid environment variables.
  • The database connection credentials provided to the container were incorrect.
  • The application takes longer to initialize than the default health check grace period.

Step-by-Step Resolution:

  1. Navigate to your stack in Stacks.
  2. Look under the “Containers” dropdown and click on Logs.
  3. Review the latest application log output to identify why the internal process failed or crashed.
  4. Verify that all required environment variables, database hosts, and secret mounts are configured correctly under Environment.
  5. In the container Settings, increase the “Start period” (grace period) for the health check to give the container more time to finish booting.
  6. Click Deploy Stacks.

9. Container Readiness Timeout

This happens when the deployment process reaches its maximum waiting time before the container reports a ready state.

Common Causes:

  • Heavy initial database migrations or asset compilation tasks running during container startup.
  • Inadequate CPU or RAM allocations causing the application to boot too slowly.

Step-by-Step Resolution:

  1. Open your container configuration under Containers > Settings.
  2. Locate the “Resource limits” section.
  3. Increase the allocated CPU cores and memory limits to provide more computing power during application boot.
  4. Open Containers > Logs to verify whether database migrations are progressing normally.
  5. Click Deploy Stacks to retry the deployment.

Best Practices for Diagnosing Stack Issues

Whenever you encounter unexpected behavior in a stack, follow this standard diagnostic procedure:

  1. Check Container Logs First: Almost all application-level failures (such as missing database tables, broken configuration files, or incorrect application ports) are printed directly to the container output logs. Always open Stack > Containers > [Container Name] > Logs first.
  2. Review Deployment Event History: Open the Deployments tab to view the chronological timeline of deployment actions and verify which stage failed.
  3. Verify Host Server Health: Check the main server dashboard to confirm that your server has adequate free RAM, available CPU capacity, and at least 20% free disk storage.

If you have any other questions or need help, please feel free to get in touch with our 24/7 support team. We’re here to help!