Skip to content

Debug Buildpack Failure

Goal

Identify and resolve failures when building container images using Cloud Native Buildpacks, enabling successful application deployment.

Prerequisites

Before you begin, ensure you have:

  • [ ] Access to the CI/CD system (Jenkins) where the build failed
  • [ ] Build logs from the failed buildpack execution
  • [ ] Source code repository access
  • [ ] pack CLI installed locally (optional, for local testing)
  • [ ] Docker installed locally (for local debugging)

Steps

1. Locate the Build Failure

Access Jenkins Build Logs

# Get Jenkins URL
echo "https://jenkins.127.0.0.1.nip.io"

# Navigate to the failed build
# Jobs → Your Pipeline → Build #XX → Console Output

Or using Jenkins CLI:

# Download Jenkins CLI
wget http://jenkins.127.0.0.1.nip.io/jnlpJars/jenkins-cli.jar

# Get build log
java -jar jenkins-cli.jar -s http://jenkins.127.0.0.1.nip.io \
  -auth admin:password \
  console my-pipeline 123  # build number

Identify the Failure Point

Look for error indicators in logs:

[detector] ======== Results ========
[detector] fail: paketo-buildpacks/node-engine@1.0.0
[detector] ERROR: No buildpack groups passed detection.
[detector] ERROR: Please check that you are running against the correct path.
ERROR: failed to build: exit status 1

Common failure patterns:

  • No buildpack groups passed detection - Buildpack couldn't detect project type
  • Unable to satisfy X dependency - Missing dependency or version conflict
  • Error during build - Build command failed
  • COPY failed - File not found during build

2. Analyze the Error Message

Understand the Failure Type

Error Pattern Cause Section to Check
No buildpack groups passed detection Wrong project structure or missing files 3. Detection Failures
Unable to satisfy dependency Version constraints or unavailable dependency 4. Dependency Issues
Error: npm install failed Node.js build error 5. Build Command Failures
Permission denied File permission issues 6. Permission Issues
Layer restoration failed Cache corruption 7. Cache Issues

3. Detection Failures

If buildpack can't detect your project type:

Verify Required Files Exist

Different buildpacks require different files:

Node.js (Paketo):

# Required: package.json in repository root
ls -la package.json

# Verify package.json is valid JSON
cat package.json | jq .

Java (Paketo):

# Required: pom.xml (Maven) or build.gradle (Gradle)
ls -la pom.xml build.gradle

# For multi-module projects, ensure parent POM exists

Python (Paketo):

# Required: requirements.txt, Pipfile, or setup.py
ls -la requirements.txt Pipfile setup.py

Go (Paketo):

# Required: go.mod
ls -la go.mod

Fix: Add Missing Files

Create the required file for your project:

# Node.js example
cat > package.json <<EOF
{
  "name": "my-app",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^4.18.0"
  }
}
EOF

# Python example
cat > requirements.txt <<EOF
flask==2.3.0
gunicorn==21.2.0
EOF

4. Dependency Issues

If dependencies can't be resolved:

Check Version Constraints

# Node.js: View dependency versions
cat package.json | jq '.dependencies, .devDependencies'

# Python: Check requirements
cat requirements.txt

# Java: Check Maven dependencies
cat pom.xml | grep -A 5 "<dependencies>"

Fix: Update Dependency Versions

# Node.js: Use compatible versions
npm install express@4.18.0

# Python: Pin versions
echo "flask==2.3.0" >> requirements.txt

# Java: Update in pom.xml
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <version>3.1.0</version>
</dependency>

Verify Dependency Availability

# Node.js: Check if package exists in npm registry
npm view express versions --json

# Python: Check PyPI
pip index versions flask

# Java: Check Maven Central
curl https://search.maven.org/solrsearch/select?q=g:org.springframework.boot+AND+a:spring-boot-starter-web

5. Build Command Failures

If the build command itself fails:

Reproduce Locally

# Test build locally with pack CLI
pack build my-app:local \
  --builder paketobuildpacks/builder:base \
  --path .

# Or use docker
docker build -t my-app:local .

Check Build Logs for Specific Errors

Common build errors:

Node.js:

ERROR: npm install failed
ENOENT: no such file or directory

Fix:

# Ensure all files are committed
git status

# Check .gitignore doesn't exclude required files
cat .gitignore

# Add missing files
git add src/config.js
git commit -m "fix: add missing config file"

Python:

ERROR: Could not find a version that satisfies the requirement

Fix:

# Use compatible Python version
echo "python_version = \"3.11\"" > runtime.txt

# Or specify in buildpack config
cat > project.toml <<EOF
[[build.env]]
name = "BP_PYTHON_VERSION"
value = "3.11.*"
EOF

Java:

ERROR: Compilation error
[ERROR] cannot find symbol

Fix:

# Build locally to identify error
mvn clean install

# Fix compilation errors in code
# Then commit and rebuild

6. Permission Issues

If build fails due to permissions:

ERROR: Permission denied
COPY failed: stat /tmp/src/app: permission denied

Fix: Correct File Permissions

# Make files readable
chmod -R 644 .

# Make directories executable
find . -type d -exec chmod 755 {} \;

# Make scripts executable
chmod +x scripts/*.sh

# Commit permission changes
git add --chmod=+x scripts/entrypoint.sh
git commit -m "fix: make entrypoint executable"

7. Cache Issues

If layer restoration fails:

ERROR: failed to restore cached layer
ERROR: layer restoration failed

Fix: Clear Build Cache

In Jenkins pipeline:

stage('Build with Buildpack') {
    steps {
        sh '''
            # Clear buildpack cache
            pack build my-app:latest \
              --builder paketobuildpacks/builder:base \
              --clear-cache \
              --path .
        '''
    }
}

Or delete cache manually:

# In CI/CD environment
rm -rf /var/cache/buildpacks/*

# Rebuild without cache

8. Configure Buildpack Behavior

Create project.toml

Customize buildpack behavior with a configuration file:

# project.toml - place in repository root
[_]
schema-version = "0.2"

[[build.env]]
name = "BP_NODE_VERSION"
value = "20.*"

[[build.env]]
name = "BP_NPM_INSTALL_ARGS"
value = "--production"

[[build.buildpacks]]
uri = "docker://gcr.io/paketo-buildpacks/nodejs:latest"

[[build.buildpacks]]
uri = "docker://gcr.io/paketo-buildpacks/npm-install:latest"

Common configuration options:

Node.js:

[[build.env]]
name = "BP_NODE_VERSION"
value = "20.*"

[[build.env]]
name = "BP_NPM_INSTALL_ARGS"
value = "--production"

Python:

[[build.env]]
name = "BP_PYTHON_VERSION"
value = "3.11.*"

[[build.env]]
name = "BP_PIP_ARGS"
value = "--no-cache-dir"

Java:

[[build.env]]
name = "BP_JVM_VERSION"
value = "17.*"

[[build.env]]
name = "BP_MAVEN_BUILD_ARGUMENTS"
value = "clean install -DskipTests"

9. Test Locally Before Pushing

Always test buildpack builds locally:

# Install pack CLI
brew install buildpacks/tap/pack  # macOS
# or download from https://buildpacks.io/docs/tools/pack/

# Build locally
pack build my-app:test \
  --builder paketobuildpacks/builder:base \
  --path .

# Run container to verify
docker run -p 8080:8080 my-app:test

# Test endpoint
curl http://localhost:8080/health

Verification

1. Verify Build Succeeds

# Re-run Jenkins build
# Or build locally
pack build my-app:verified \
  --builder paketobuildpacks/builder:base \
  --path .

# Should complete without errors
# Look for: Successfully built image my-app:verified

2. Verify Image Runs

# Run the built image
docker run -d -p 8080:8080 --name test-app my-app:verified

# Check container is running
docker ps | grep test-app

# Check logs for errors
docker logs test-app

# Test application endpoints
curl http://localhost:8080
curl http://localhost:8080/health

# Clean up
docker rm -f test-app

3. Verify Buildpack Metadata

# Inspect image for buildpack metadata
pack inspect my-app:verified

# Should show:
# - Buildpacks used
# - Runtime version
# - Build processes
# - Launch processes

4. Verify in CI/CD Pipeline

# Trigger Jenkins build
# Navigate to Console Output

# Verify all stages pass:
# [detector] ✓ paketo-buildpacks/node-engine
# [analyzer] ✓ Layer restoration successful
# [builder] ✓ Build completed successfully
# [exporter] ✓ Image exported

Common Buildpack Issues and Solutions

Issue: "No buildpack groups passed detection"

Solution:

# Ensure correct file structure
ls -la package.json  # Node.js
ls -la pom.xml       # Java
ls -la requirements.txt  # Python

# Specify builder explicitly
pack build my-app --builder paketobuildpacks/builder:full

Issue: "Unable to satisfy node version"

Solution:

# Add to project.toml
[[build.env]]
name = "BP_NODE_VERSION"
value = "20.*"  # Use wildcard for flexibility

Issue: "npm install fails with network error"

Solution:

# Configure npm registry
[[build.env]]
name = "NPM_CONFIG_REGISTRY"
value = "https://registry.npmjs.org"

# Or use .npmrc
echo "registry=https://registry.npmjs.org" > .npmrc

Issue: "Out of memory during build"

Solution:

// Increase memory in Jenkins pipeline
stage('Build') {
    environment {
        PACK_MEMORY_LIMIT = '4G'
    }
    steps {
        sh 'pack build my-app --memory 4G'
    }
}

Troubleshooting Checklist

  • [ ] Required manifest file exists (package.json, pom.xml, etc.)
  • [ ] Manifest file is valid (JSON/XML syntax)
  • [ ] Dependencies are available and versions are compatible
  • [ ] Build commands succeed locally
  • [ ] File permissions are correct
  • [ ] No sensitive files in repository (check .gitignore)
  • [ ] Buildpack version is up to date
  • [ ] Correct builder is specified
  • [ ] Cache is not corrupted

Next Steps

After resolving buildpack issues: