Skip to content

troubleshooting.mdx

Latest commit

 

History

History
172 lines (118 loc) · 5.11 KB

troubleshooting.mdx

File metadata and controls

172 lines (118 loc) · 5.11 KB
description Common issues and solutions for Phala Cloud deployments.
title Troubleshooting Guide

Join our support groups: 🌍 Global, 🇨🇳 Chinese

Deployment Errors

No available nodes found

This error indicates no available nodes for deployment.

Common causes:

  • You've reached your tier's CVM limit
  • All nodes are currently at capacity

Solutions:

  1. Check your account tier limits
  2. Delete unused CVMs to free up capacity
  3. Upgrade to a higher tier for more resources
  4. Try again later if nodes are temporarily at capacity

No available nodes found

Can't deploy more CVMs - tier limit reached

Each account tier has CVM limits:

Tier Max CVMs Max vCPUs Max Memory
Tier 1 8 16 32GB
Tier 2 16 32 64GB
Enterprise Unlimited Unlimited Unlimited

Solutions:

Deployment blocked - "violates terms & conditions"

Some Docker images trigger anti-spam rules.

Known triggers:

  • Certain base images that have been abused for spam
  • Images with suspicious patterns

Solutions:

  1. Use official base images (e.g., python:3.11, node:20)
  2. Avoid deprecated or unmaintained base images
  3. Contact support if you believe your image was incorrectly flagged

CVM stuck, can't restart - "process already running"

If your CVM is stuck and won't restart:

Solution: Use the "Power Off" button in the Web UI for a force shutdown. This is different from "Stop" and will forcefully terminate the CVM.

  1. Go to your CVM in the dashboard
  2. Click Power Off (not Stop)
  3. Wait for the CVM to fully shut down
  4. Start the CVM again

If this doesn't work, contact support for assistance.

Container & Image Errors

exec format error

exec /usr/local/bin/docker-entrypoint.sh: exec format error

Your Docker image is not compatible with x86_64 architecture. This happens when building on ARM (e.g., Apple Silicon Mac).

Solution: Build your image with the correct platform:

docker build --platform linux/amd64 -t your-image:tag .

Or in docker-compose.yml:

services:
  your-service:
    platform: linux/amd64
    build: .

TEE socket error - "No such file or directory" for dstack.sock

Error: /var/run/dstack.sock: No such file or directory

Cause: Incorrect volume configuration in docker-compose.yml.

Solution: Only mount the socket file, NOT the lock file:

# ✅ Correct
volumes:
  - /var/run/dstack.sock:/var/run/dstack.sock

# ❌ Wrong - remove this line
# - /var/run/dstack.sock.lock:/var/run/dstack.sock.lock

[FAILED] Failed to start Virtual Console Setup

You can safely ignore this error. This is a known issue in OS image dstack v0.5.4 where the virtual console module was partially removed.

Networking Issues

Can't expose non-HTTPS ports

By default, Phala Cloud only exposes HTTPS/TLS ports to the public internet.

For TCP services (SSH, databases, etc.):

For DNS servers: Running a DNS server on Phala Cloud is possible but requires workarounds since UDP port 53 cannot be directly exposed. Consider running DNS on a separate server and connecting to your TEE backend.

SSH connection issues

See the SSH access guide for detailed troubleshooting.

Common issues:

  • Not using Development OS image (SSH is disabled on Production OS)
  • Missing DSTACK_ROOT_PASSWORD or DSTACK_ROOT_PUBLIC_KEY environment variables
  • Using LibreSSL instead of OpenSSL on macOS

GPU TEE Issues

"Resource matching failed: No teepod found"

No GPU nodes are currently available matching your requirements.

Solutions:

  1. Try a different GPU configuration (fewer GPUs)
  2. Try again later when resources become available
  3. Contact cloud@phala.network for dedicated capacity

For refunds on failed provisions: Email support@phala.network with:

  • Payment Order ID
  • Order reference

GPU billing questions

See GPU TEE Billing for details on:

  • 24-hour minimum charges
  • When billing starts (only on launch)
  • Commitment pricing options

API Error Codes

If you encounter API errors with codes like ERR-01-xxx or ERR-02-xxx, see the Error Codes Reference for a complete list of error codes and their meanings.

Still Need Help?