Troubleshooting

This guide helps you diagnose and resolve common issues when deploying your frontend applications.

Quick Diagnostics

Before diving into specific issues, run these quick checks:

Verify API Response

Ensure you received a successful response from the deployment API:

{"success": true, "id": "your-deployment-id"}

If not, see API Request Failures.

Check Build Queue

Verify your deployment is in or has been processed from the queue:

redis-cli LLEN build-queue

Review Server Logs

Check both upload-service and deploy-service logs for errors.

Common Issues

API Request Failures

Error: 'Failed to clone repository'

Error Message:

{
  "error": "Failed to clone repository"
}

Cause: The platform couldn’t clone your Git repository.Solutions:

Verify Repository URL

# Test cloning locally
git clone https://github.com/username/repo.git

Check Repository Access
- Ensure the repository is public, or
- Use HTTPS with embedded credentials: https://[email protected]/user/repo.git
- Check if the repository URL is correct and active
Network Issues
- Verify the platform server has internet access
- Check for firewall rules blocking Git operations
- Ensure DNS resolution works for Git host

Server Logs: Check upload service logs for detailed error:

# Look for "Clone error:" messages
docker logs upload-service 2>&1 | grep "Clone error"

No Response from API

Symptom: The API request hangs or times out.Solutions:

Check Server Status
```
curl http://your-platform:3000/
```
Verify Port 3000 is Accessible
```
telnet your-platform 3000
```

Check Upload Service Logs

docker ps | grep upload-service
docker logs upload-service

Restart Upload Service
```
docker restart upload-service
```

Invalid Request Body

Cause: Missing or malformed url field in request body.Solution: Ensure your request includes the url field:

curl -X POST http://platform:3000/get/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/user/repo.git"}'

The field must be named url, not repoUrl or repository.

Build Process Failures

Build Failures: npm install Errors

Symptom: Build fails during dependency installation.Common Causes:

Missing package.json
- Ensure package.json is in the repository root
- Check that it wasn’t ignored by .gitignore
Invalid package.json
```
# Validate locally
npm install
```
Network Issues in Container
- Check Docker container has internet access
- Verify npm registry is accessible
Platform-Specific Dependencies
- The build uses node:20-alpine base image
- Some native modules may need additional build tools

Debug Command:

# Test build in same environment
docker run -it --rm -v $(pwd):/app -w /app node:20-alpine sh
npm install
npm run build

Build Failures: npm run build Errors

Symptom: Installation succeeds but build script fails.Solutions:

Missing Build Script Verify package.json includes:

{
  "scripts": {
    "build": "your-build-command"
  }
}

Wrong Output Directory The platform expects output in /app/build or /app/dist. If your framework uses a different directory, modify your build script:
```
{
  "scripts": {
    "build": "webpack --output-path=./build"
  }
}
```

TypeScript Errors

{
  "scripts": {
    "build": "tsc --noEmit false"
  }
}

Memory Issues Large projects may run out of memory:

{
  "scripts": {
    "build": "NODE_OPTIONS=--max-old-space-size=4096 react-scripts build"
  }
}

Build Output Not Found

Error in Logs:

docker cp build-container-{id}:/app/build failed
docker cp build-container-{id}:/app/dist failed

Cause: Build doesn’t output to build/ or dist/ directory.Solution: Configure your build to output to one of these directories.Framework Examples:

Vite (default: dist/) - No change needed
Create React App (default: build/) - No change needed

Next.js:

{
  "scripts": {
    "build": "next build && next export -o build"
  }
}

Angular:

{
  "scripts": {
    "build": "ng build --output-path=dist"
  }
}

Docker Issues

Docker Build Failures

Symptom: Build command execution fails with Docker errors.Solutions:

Docker Service Not Running

sudo systemctl status docker
sudo systemctl start docker

Insufficient Disk Space
```
df -h
docker system prune -a
```

Docker Permission Issues

sudo usermod -aG docker $USER
newgrp docker

Cleanup Orphaned Containers

# Remove old build containers
docker ps -a | grep build-container- | awk '{print $1}' | xargs docker rm

# Remove old build images
docker images | grep frontend-build- | awk '{print $3}' | xargs docker rmi

Container Build Timeout

Symptom: Build takes too long and times out.Solutions:

Reduce Dependencies
- Remove unused packages from package.json
- Use lightweight alternatives
Optimize Docker Build
- The platform creates a fresh Dockerfile for each build
- Consider caching strategies

Check System Resources

# Monitor during build
docker stats
top

S3 Upload Issues

Upload Errors

Error in Logs:

Upload error: ...

Cause: Failed to upload files to S3 storage.Solutions:

Check AWS Credentials

# Verify environment variables
echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY
echo $AWS_REGION

Test S3 Access
```
aws s3 ls s3://vercel-frontend/
```
Verify Bucket Permissions
- Ensure the IAM user has s3:PutObject permission
- Check bucket policy allows uploads
Check Network Connectivity
```
curl -I https://s3.amazonaws.com
```

Download Errors (Deploy Service)

Error in Logs:

Error downloading file from S3

Cause: Deploy service can’t download files uploaded by upload service.Solutions:

Verify Files Were Uploaded

aws s3 ls s3://vercel-frontend/output/{deployment-id}/

Check Deploy Service Credentials
- Ensure deploy service has s3:GetObject and s3:ListBucket permissions
Disk Space on Deploy Server
```
df -h
```

Queue Problems

Build Never Starts

Symptom: Deployment ID received but build never processes.Solutions:

Check Redis Connection
```
redis-cli ping
# Should return: PONG
```

Verify Build Queue

# Check if your ID is in queue
redis-cli LRANGE build-queue 0 -1

Check Deploy Service Status

docker ps | grep deploy-service
docker logs deploy-service

Restart Deploy Service
```
docker restart deploy-service
```

Redis Connection Errors

Error in Logs:

Redis Client Error
Redis error: ...

Solutions:

Check Redis Service

docker ps | grep redis
systemctl status redis

Restart Redis

docker restart redis
# or
sudo systemctl restart redis

Verify Redis Configuration
- Default connection expects Redis on localhost:6379
- Check firewall rules

Debugging Tips

Enable Verbose Logging

Set log levels for more detailed output:

# In your environment
export DEBUG=*
export LOG_LEVEL=debug

Manual Build Testing

Test the build process locally:

# Clone repository
git clone <your-repo-url> test-deploy
cd test-deploy

# Create the same Dockerfile
cat > Dockerfile << 'EOF'
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EOF

# Build and extract
docker build -t test-build .
docker create --name test-container test-build
docker cp test-container:/app/build ./build || \
  docker cp test-container:/app/dist ./build
docker rm test-container

# Verify output
ls -la build/

Check End-to-End Flow

Trace your deployment through each service:

# 1. Upload Service
curl -X POST http://platform:3000/get/url \
  -H "Content-Type: application/json" \
  -d '{"url": "<repo-url>"}'
# Note the ID

# 2. Check S3 Upload
aws s3 ls s3://vercel-frontend/output/<deployment-id>/

# 3. Check Queue
redis-cli LRANGE build-queue 0 -1

# 4. Monitor Deploy Service
docker logs -f deploy-service

# 5. Check Final Output
aws s3 ls s3://vercel-frontend/dist/<deployment-id>/

# 6. Access Site
curl http://your-cdn/dist/<deployment-id>/index.html

Common Log Patterns

Successful Deployment:

# Upload Service
Clone complete
reached1
File uploaded successfully (repeated for each file)

# Deploy Service  
Response { key: 'build-queue', element: '<id>' }
stdout: Successfully built <docker-image-id>
stdout: Successfully tagged frontend-build-<id>
File uploaded successfully (repeated for each built file)
Project uploaded successfully

Failed Deployment:

# Look for these indicators
Clone error: ...
Execution error: ...
stderr: ... (build errors)
Upload error: ...
Error downloading file from S3: ...
Redis error: ...

Getting Help

Still Stuck?

If you’ve tried these solutions and still have issues:

Collect deployment ID and timestamps
Gather relevant log snippets
Document steps to reproduce
Contact platform support with details

Prevention Best Practices

Test Before Deploying

Run npm install && npm run build locally
Test in a Docker container with node:20-alpine
Verify build outputs to correct directory
Check repository is accessible

Monitor Your Deployments

Keep deployment IDs organized
Set up log monitoring
Track build times to detect anomalies
Monitor S3 storage usage

Maintain Your Repository

Keep dependencies updated
Remove unused packages
Document build requirements
Test build process in CI/CD

Get Started

Core Features

Configuration

Guides

Quick Diagnostics

Common Issues

API Request Failures

Build Process Failures

Docker Issues

S3 Upload Issues

Queue Problems

Debugging Tips

Enable Verbose Logging

Manual Build Testing

Check End-to-End Flow

Common Log Patterns

Getting Help

Still Stuck?

Prevention Best Practices

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Guides

​Quick Diagnostics

​Common Issues

​API Request Failures

​Build Process Failures

​Docker Issues

​S3 Upload Issues

​Queue Problems

​Debugging Tips

​Enable Verbose Logging

​Manual Build Testing

​Check End-to-End Flow

​Common Log Patterns

​Getting Help

Still Stuck?

​Prevention Best Practices

Build docs developers (and LLMs) love

Quick Diagnostics

Common Issues

API Request Failures

Build Process Failures

Docker Issues

S3 Upload Issues

Queue Problems

Debugging Tips

Enable Verbose Logging

Manual Build Testing

Check End-to-End Flow

Common Log Patterns

Getting Help

Prevention Best Practices