Troubleshooting

This guide covers common issues you may encounter when deploying and running the application.

Docker Issues

Port 5000 already in use

Error Message:

Error starting userland proxy: listen tcp4 0.0.0.0:5000: bind: address already in use

Cause: Another process is already using port 5000, which is required by the application (docker-compose.yml:6 and server/index.js:11).Solutions:

Find and stop the process using port 5000:

# Linux/Mac
lsof -i :5000
kill -9 <PID>

# Or using netstat
netstat -tulpn | grep :5000

Stop conflicting Docker container:

docker ps -a | grep 5000
docker stop <container_id>
docker rm <container_id>

Use a different port temporarily: Edit docker-compose.yml to map to a different host port:
```
ports:
  - "5001:5000"  # Access via localhost:5001
```

If you change the port, update your health check commands and any frontend API calls accordingly.

Docker build failures

Error Message:

ERROR [frontend-build 4/5] RUN cd client && npm install
npm ERR! network request failed

Cause: Network issues, corrupted cache, or missing dependencies during the multi-stage build process (Dockerfile:4-14).Solutions:

Clear Docker build cache:

docker builder prune
docker build --no-cache -t react-express-app .

Check internet connectivity:
```
curl -I https://registry.npmjs.org/
```

Verify package.json files exist:

ls -la client/package.json
ls -la server/package.json

Check Docker daemon status:

docker info
systemctl status docker  # Linux

Increase Docker resources:
- Go to Docker Desktop > Settings > Resources
- Increase Memory to at least 4GB
- Increase Disk space if needed

Container won't start or exits immediately

Error Message:

docker: Error response from daemon: container miniproject is not running

Cause: The container starts but exits due to application errors or missing files.Solutions:

Check container logs for errors:
```
docker logs miniproject
```
Verify the built frontend exists:
```
docker run --rm react-express-app ls -la /app/server/client/build
```
This should show the built React files copied in Dockerfile:43.
Check if Node.js can start the server:
```
docker run --rm react-express-app node server/index.js
```
Expected output: ✅ Server running on port 5000
Verify the Dockerfile CMD is correct: The Dockerfile:49 should have:
```
CMD ["node", "server/index.js"]
```

Run container in interactive mode for debugging:

docker run -it --rm react-express-app /bin/sh
ls -la /app
node server/index.js

Docker image build is very slow

Cause: Multi-stage builds and npm installs can be slow, especially when rebuilding frequently.Solutions:

Use Docker layer caching effectively: The Dockerfile already copies package*.json before source code (Dockerfile:9, 25), which helps cache npm install layers.
Check .dockerignore file: Create/verify .dockerignore to exclude unnecessary files:
```
node_modules
npm-debug.log
.git
.env
dist
build
```

Use BuildKit for faster builds:

DOCKER_BUILDKIT=1 docker build -t react-express-app .

Build only when needed: Use docker-compose to avoid rebuilding unnecessarily:
```
docker-compose up -d  # Only rebuilds if Dockerfile changed
```

Cannot connect to Docker daemon

Error Message:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Cause: Docker daemon is not running or user lacks permissions.Solutions:

Start Docker daemon:

# Linux
sudo systemctl start docker

# Mac/Windows
# Start Docker Desktop application

Add user to docker group (Linux):

sudo usermod -aG docker $USER
# Log out and log back in

Verify Docker is running:
```
docker info
```

Jenkins Pipeline Issues

Jenkins pipeline fails at Build Docker Image stage

Error in Jenkins Console:

ERROR: permission denied while trying to connect to the Docker daemon socket

Cause: Jenkins user doesn’t have permission to access Docker.Solutions:

Add Jenkins user to docker group:

sudo usermod -aG docker jenkins
sudo systemctl restart jenkins

Verify Docker socket permissions:

ls -la /var/run/docker.sock
sudo chmod 666 /var/run/docker.sock

Check Jenkinsfile build command: Verify Jenkinsfile:14 has:
```
sh 'docker build -t react-express-app .'
```

Pipeline fails at Run Container stage

Error in Jenkins Console:

docker: Error response from daemon: Conflict. The container name "/react-express-app" is already in use

Cause: Old container wasn’t properly stopped/removed.Solutions:

Verify cleanup command in Jenkinsfile: The Jenkinsfile:23 should properly stop and remove old containers:

sh 'docker ps -q --filter "name=react-express-app" | grep -q . && docker stop react-express-app && docker rm react-express-app || true'

Manually clean up containers:

docker stop react-express-app
docker rm react-express-app

Force remove if container is stuck:
```
docker rm -f react-express-app
```

Note that the Jenkinsfile uses container name react-express-app, while docker-compose uses miniproject. Make sure you’re working with the correct container.

Git checkout fails in Jenkins

Error in Jenkins Console:

ERROR: Error cloning remote repo 'origin'

Cause: Git credentials not configured or network issues.Solutions:

Verify repository URL in Jenkinsfile: Check Jenkinsfile:7:

git branch: 'main', url: 'https://github.com/mani-6666/Mini-Project.git'

Test Git connectivity from Jenkins server:

git ls-remote https://github.com/mani-6666/Mini-Project.git

Configure Git credentials in Jenkins:
- Go to Jenkins > Credentials
- Add GitHub credentials
- Update Jenkinsfile to use credentials
Check network/firewall settings: Ensure Jenkins server can access GitHub.

Jenkins build succeeds but application not accessible

Symptom: Pipeline shows success, but curl http://localhost:5000 fails.Cause: Container started but application failed, or port mapping incorrect.Solutions:

Check container status:
```
docker ps -a | grep react-express-app
```
View container logs:
```
docker logs react-express-app
```
Should show: ✅ Server running on port 5000

Verify port mapping: Check Jenkinsfile:25:

sh 'docker run -d -p 5000:5000 --name react-express-app react-express-app'

Test from within container:

docker exec react-express-app curl http://localhost:5000

Check if port is listening:
```
netstat -tulpn | grep :5000
```

Application Issues

Node modules issues

Error Message:

Error: Cannot find module 'express'

Cause: Dependencies not installed during build or incorrect COPY commands in Dockerfile.Solutions:

Verify dependencies are installed in Dockerfile: Check Dockerfile:10 and Dockerfile:26:
```
RUN cd client && npm install
RUN cd server && npm install
```

Verify server dependencies: Check server/package.json includes:

{
  "dependencies": {
    "cors": "^2.8.5",
    "express": "^5.1.0"
  }
}

Rebuild without cache:

docker build --no-cache -t react-express-app .

Check COPY commands in production stage: Verify Dockerfile:40 copies server with node_modules:
```
COPY --from=backend-build /app/server ./server
```

CORS errors in browser

Error in Browser Console:

Access to fetch at 'http://localhost:5000' from origin 'http://localhost:3000'
has been blocked by CORS policy

Cause: CORS middleware not configured properly.Solutions:

Verify CORS is enabled: Check server/index.js:2,5:

const cors = require('cors');
app.use(cors());

Check cors dependency is installed: Verify server/package.json includes cors: ^2.8.5

Rebuild and restart container:

docker-compose down
docker-compose up -d --build

Configure specific CORS origins if needed:

app.use(cors({
  origin: 'http://localhost:3000'
}));

Frontend not loading (404 errors)

Symptom: Backend works, but React frontend returns 404.Cause: Frontend build not copied correctly or Express not serving static files.Solutions:

Verify frontend build was copied: Check Dockerfile:43:

COPY --from=frontend-build /app/client/build ./server/client/build

Check build exists in container:

docker exec miniproject ls -la /app/server/client/build

Add static file serving to Express: Update server/index.js to serve the React build:

const path = require('path');
app.use(express.static(path.join(__dirname, 'client/build')));

app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'client/build', 'index.html'));
});

Verify React build completed successfully: Check build logs for errors in Dockerfile:14 stage.

Environment variables not working

Symptom: Application can’t read environment variables.Cause: Environment variables not passed to container.Solutions:

Add environment variables to docker-compose.yml:

services:
  app:
    environment:
      - NODE_ENV=production
      - PORT=5000

Or use .env file:

services:
  app:
    env_file:
      - .env

Pass via docker run:

docker run -d -p 5000:5000 -e NODE_ENV=production miniproject

Verify in server/index.js: The app uses process.env.PORT || 5000 (server/index.js:11)

Getting Help

If you continue to experience issues after trying these solutions, collect the following information:

Docker version: docker --version
Docker Compose version: docker-compose --version
Container logs: docker logs miniproject
Docker inspect output: docker inspect miniproject
System resources: docker stats --no-stream

This information will help diagnose the problem more effectively.

For issues not covered here, check the container logs first:

docker logs miniproject

Most issues will have error messages in the logs that point to the root cause.

Getting Started

Architecture

Deployment

Development

Operations

Docker Issues

Jenkins Pipeline Issues

Application Issues

Getting Help

Build docs developers (and LLMs) love

Getting Started

Architecture

Deployment

Development

Operations

​Docker Issues

​Jenkins Pipeline Issues

​Application Issues

​Getting Help

Build docs developers (and LLMs) love

Docker Issues

Jenkins Pipeline Issues

Application Issues

Getting Help