Skip to main content

Troubleshooting

Docker Startup Failure​

Database Migration Error no such table​

Symptom: Container logs show Failed to run database migrations: no such table: collaborator

Cause: Migration sequence issue in old version images (already fixed)

Solution: Rebuild the image

docker compose build --no-cache server
docker compose up -d

Container Keeps Restarting​

Troubleshooting steps:

docker logs iforge-server --tail 50

Common causes:

  • Port is occupied → Modify the port in .env
  • Insufficient data directory permissions → chmod -R 755 ./data

CORS Cross-Origin Errors​

Symptom: Browser console shows blocked by CORS policy

Cause: Backend CORS configuration did not take effect

Solution:

  1. Confirm the server service in docker-compose.yml has IFORGE_CORS_ORIGINS=*
  2. Confirm the web service has SERVER_API_URL=http://server:8081/api/v1
  3. Rebuild: docker compose build --no-cache server web

Frontend API Requests Going to localhost​

Symptom: When accessing from LAN, API requests are sent to http://localhost:8081 instead of the actual IP

Cause: The default value of NEXT_PUBLIC_API_BASE in the web Dockerfile was not changed to empty

Solution: Confirm ARG NEXT_PUBLIC_API_BASE= (empty value) in the web Dockerfile, rebuild the web image.

Git push Returns 404​

Symptom: git push returns 404 page not found

Troubleshooting:

# Test if backend is working normally
curl http://localhost:8081/health

# Test Git HTTP endpoint
curl http://localhost:8081/owner/repo.git/info/refs?service=git-upload-pack

Common causes:

  • Backend not started or wrong port
  • Repository does not exist or no permission
  • Backend process abnormal (restart backend)

SSH clone Fails​

Symptom: git clone ssh://git@host:2022/owner/repo.git times out or connection refused

Troubleshooting:

# Test SSH port
ssh -T git@host -p 2022

# Confirm key has been added
ssh -v git@host -p 2022

Common causes:

  • SSH port not open (firewall/security group)
  • SSH key not added in iForge
  • IFORGE_SSH_ENABLED=false

WebSocket Connection Failure​

Symptom: Browser console shows WebSocket connection failed: 404

Cause: Missing WebSocket upgrade middleware (already fixed)

Solution: Rebuild the server image.

Database Switching​

The current version supports three databases: SQLite/MySQL/PostgreSQL. Switch through Docker Compose profiles:

# MySQL
IFORGE_DB_DRIVER=mysql
docker compose --profile mysql up -d

# PostgreSQL
IFORGE_DB_DRIVER=postgres
docker compose --profile postgres up -d

See Docker Deployment - Database Selection for details.

info

SQLite is sufficient for small to medium teams (< 100 people), with simple single-file backup and no need for additional database operations.

Job Execution Failed: Shell Executor is disabled​

Symptom: Pipeline Job logs show ERROR: Shell Executor is disabled for security reasons.

Cause: Job did not specify the image field, attempting to use Shell Executor to execute on the host

Solution: Add the image field to the Job in .iforge-ci.yml:

test:
  stage: test
  image: golang:1.21  # Image must be specified
  script:
    - go test ./...

Job Container Out of Memory​

Symptom: Job logs show OOMKilled or container terminated

Cause: Job container memory exceeded 2GB limit

Solution:

  1. Optimize build scripts to reduce memory usage
  2. Use smaller base images
  3. Build in stages to avoid loading large amounts of data at once

Job Cannot Access Network​

Symptom: Network commands like curl, wget, git clone fail in Jobs

Cause: Job containers have network access disabled by default (--network=none)

Solution: This is a security design; Job containers should not access external networks. If you need to download dependencies, pre-install them when building the image, or use artifact caching.