Troubleshooting
Common issues and their solutions.
Deployment Issues
Build Fails
Symptom: Status shows "error" after deployment
How to check: 1. Open the "Deploy History" tab in the app detail screen 2. Select the failed deployment and check the logs
Common causes and solutions:
| Cause | Solution |
|---|---|
| Dependency installation error | Check package.json, go.mod, or other dependency files |
| Build command error | Check the pre-deploy command. Verify it works locally |
| Node.js version mismatch | Specify version in package.json engines field |
| Out of memory | Upgrade spec (Nano is fixed for Free plan) |
Node.js example:
{
"engines": {
"node": ">=18.0.0"
}
}
Health Check Fails
Symptom: Build succeeds but app doesn't become "running"
How to check: 1. Verify health check endpoint is correct 2. Check app logs for errors
Common causes and solutions:
| Cause | Solution |
|---|---|
| Endpoint doesn't exist | Implement a /health endpoint |
| Wrong port | Listen on the PORT environment variable |
| Slow startup | Optimize startup process |
Example (Node.js):
const PORT = process.env.PORT || 3000;
app.get('/health', (req, res) => {
res.status(200).json({ status: 'ok' });
});
app.listen(PORT, '0.0.0.0', () => {
console.log(`Server running on port ${PORT}`);
});
Example (Go):
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
w.Write([]byte(`{"status":"ok"}`))
})
http.ListenAndServe("0.0.0.0:"+port, nil)
Changes Not Reflected After Redeploy
Check:
- Did you push to the correct branch?
- Did the build succeed? (Check deploy history)
- Clear browser cache
Database Issues
Cannot Connect to Database
How to check: 1. Verify database status is "running" 2. Verify connection info (URL, host, port, etc.) is correct
Common causes and solutions:
| Cause | Solution |
|---|---|
| Environment variables not set | Connect database in app settings |
| Database is starting | Wait a few minutes and retry |
| Connection limit reached | Use connection pooling and limit connections |
Connection Timeouts
Cause: Idle connections are timed out after long periods
Solutions: - Use connection pooling - Configure connection keep-alive - Implement retry logic
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
max: 10,
idleTimeoutMillis: 30000,
connectionTimeoutMillis: 2000,
});
CLI Issues
"not logged in" Error
Cause: Not authenticated or token expired
Solution:
kamui login
"session expired" Error
Solution:
kamui logout
kamui login
Browser Doesn't Open Automatically
Solution: Copy and paste the URL shown in the terminal into your browser manually
"project not found" Error
Check:
1. Is the project name or ID correct?
2. Verify with kamui projects list
Static Site Issues
"index.html not found" Error
Cause: No index.html in the specified directory
Solution:
- Check build output directory (dist, build, etc.)
- Run build locally and verify output
SPA Returns 404 on Reload
Cause: Server-side routing not configured
Solution: Kamui Platform automatically falls back to index.html for SPAs.
Performance Issues
App is Slow
Check: 1. Is the spec appropriate (CPU, memory)? 2. Are database queries optimized? 3. Are external API calls causing bottlenecks?
Solutions: - Upgrade spec - Add database indexes - Implement caching
Out of Memory (OOM)
Symptoms: App suddenly stops, keeps restarting
Solutions: 1. Upgrade spec 2. Check for memory leaks 3. Reduce data processed at once
Other
If the Problem Persists
- Check logs: Review app logs and deploy logs for detailed error information
- Check dashboard: Re-verify status and settings
- Redeploy: For temporary issues, redeploying may resolve the problem