Serverless Troubleshooting

Other languages:English|日本語|한국어|Deutsch

If the solution below does not resolve your issue, feel free to join our Leapcell Discord community for further assistance.

Join Discord

Service Lifecycle

Service Startup

The diagram below illustrates the full process of how your service starts inside a Leapcell Linux VM.

1. We execute your configured start command via Bash.
   • If your command fails, please check whether your build command missed any dependencies.
2. We continuously poll 0.0.0.0:{your_port}/kaithhealth to verify that your port is listening.
3. Once startup is complete, we route external traffic to your running service.

Serverless Environment Constraints

For more comparisons between Serverless and Persistent Server, please refer to: serverless vs persistent server

Constraint	Description	Notes / Recommendations
Filesystem	Only the /tmp path is writable; all other paths are read-only.	Machines are highly dynamic; the next request may hit a different instance and will not retain previous data. For fully writable paths, use a Persistent Server.
HTTP Short-Lived Requests Only	Leapcell serverless services are dynamic and optimized for request-response patterns.	For streaming services (e.g., WebSocket), consider a Persistent Server, which is better suited for long-running services.
Request Timeout	Maximum execution time for a single request is 15 minutes.	For tasks exceeding this limit, use a Persistent Server.
CPU Suspension	During idle periods, the instance's CPU is suspended.	No background tasks can run when there are no incoming requests.

Common Errors

Common Errors and Solutions

Error	Cause	Solution
Read-only file system or Permission denied	Leapcell prioritizes ultra-fast cold start performance, so only the /tmp directory is writable. All other directories are read-only.	Ensure any files your application writes are directed to the /tmp directory. See Storage Documentation for details.
Shared Memory: /dev/shm Permission Denied	/dev/shm is read-only in the Leapcell environment, so shared memory is not supported.	Use pipes or sockets for inter-process communication instead.
Response is bigger than the maximum allowed size	Leapcell limits the response size to 6 MB.	For larger data, store it in object storage and return the object’s URL instead.
Port Some(8080) is not being listened to by the service	The application is not listening on the correct port.	Ensure your application listens on the port configured in the Settings.
Execution Environment User vs. Build Environment User Mismatch	During build, the user has root permissions. In execution, the app runs as a non-root user.	Adapt operations that require root permissions to work under the execution environment’s constraints.