Bitbucket Pipeline Failed: Complete Troubleshooting Guide

# Bitbucket Pipeline Failed: Complete Troubleshooting Guide

Your Bitbucket pipeline failed, and now you're looking at a log with cryptic error messages. Bitbucket Pipelines uses a Docker-based approach that can fail for many reasons—YAML issues, Docker problems, SSH authentication, or deployment errors.

Let me walk through the most common Bitbucket pipeline failures and how to fix each one.

Reading Bitbucket Pipeline Logs

First, understand how to find the actual error:

1. 1.Go to your repository's Pipelines tab
2. 2.Click on the failed pipeline run
3. 3.Click on the failed step (marked with red)
4. 4.Scroll through the log for error indicators

Look for lines starting with: - ERROR: - Failed - fatal: - docker: - Exit code 127 (command not found)

Fix 1: YAML Configuration Errors

The bitbucket-pipelines.yml file is strict about syntax.

Symptoms: - Pipeline doesn't start - "Configuration error" message - Steps run in unexpected order

Diagnosis:

Bitbucket validates YAML before running. Check for:

# WRONG - wrong indentation
pipelines:
  default:
    - step:
        name: Build
      script:  # Wrong indentation level
        - npm install

Correct format:

```yaml # CORRECT pipelines: default: - step: name: Build script: - npm install - npm run build

# Or with alternative syntax pipelines: default: - step: name: Build script: | npm install npm run build ```

Common YAML issues:

```yaml # Problem: Missing quotes for special characters script: - echo "Hello $BITBUCKET_BRANCH"

# Problem: Using wrong pipe type pipelines: branches: main: # For main branch - step: script: - ./deploy.sh

tags: v*: - step: # For tags starting with v script: - ./release.sh ```

Solution: Validate your YAML:

```bash # Use yamllint locally pip install yamllint yamllint bitbucket-pipelines.yml

# Or use Bitbucket's built-in validation # Go to Pipelines → Settings → "Validate YAML" ```

Fix 2: Docker Image Issues

Bitbucket Pipelines runs all builds in Docker containers.

Symptoms: - "Unable to find image locally" - "Error pulling image" - Container crashes immediately

Default image not found:

```yaml # Default image is at the top level image: node:20

pipelines: default: - step: script: - npm install ```

Solution A: Use public images:

```yaml image: node:20.11.0 # Specific version

# Or use Atlassian's images image: atlassian/default-image:4 # Has common tools pre-installed ```

Solution B: Per-step images:

```yaml pipelines: default: - step: name: Node Build image: node:20 script: - npm install

• step:
• name: Python Test
• image: python:3.11
• script:
• - pip install pytest
• - pytest
• `

Solution C: Use private images:

pipelines:
  default:
    - step:
        name: Build
        image: your-org/your-image:latest
        script:
          - ./build.sh

For private images, add authentication:

1. 1.Go to Repository Settings → Pipelines → Docker image credentials
2. 2.Add credentials for your registry

Or in YAML:

pipelines:
  default:
    - step:
        name: Build
        image:
          name: your-registry.com/your-image:latest
          username: $DOCKER_USERNAME
          password: $DOCKER_PASSWORD
        script:
          - ./build.sh

Fix 3: Command Not Found

Running commands that aren't in the Docker image:

bash: npm: command not found
bash: python: command not found

Solution A: Choose correct image:

```yaml # For Node.js projects image: node:20 # Has npm, node

# For Python projects image: python:3.11 # Has python, pip

# For Java projects image: openjdk:17 # Has java, javac

# For Go projects image: golang:1.21 # Has go ```

Solution B: Install missing tools:

- step:
    name: Build
    image: atlassian/default-image:4
    script:
      - apt-get update && apt-get install -y jq  # Install jq
      - jq --version

Solution C: Use a custom image:

Create your own Dockerfile:

# Dockerfile
FROM node:20
RUN apt-get update && apt-get install -y jq awscli

Build and push to registry, then use in pipeline:

image: your-org/custom-node:latest

Fix 4: SSH Authentication Failures

Deployments requiring SSH access fail:

Permission denied (publickey)
Host key verification failed

Solution A: Add SSH key to Bitbucket:

1. 1.Generate SSH key:

ssh-keygen -t rsa -b 4096 -C "bitbucket-pipeline"

1. 1.Add public key to your server:

ssh-copy-id -i ~/.ssh/bitbucket-pipeline.pub user@server.com

1. 1.Add private key to Bitbucket:
2. 2.- Go to Repository Settings → Pipelines → SSH keys
3. 3.- Click "Add SSH key"
4. 4.- Paste private key content
5. 5.- Note the key name (e.g., my-deploy-key)
6. 6.Add known hosts:
7. 7.- Click "Add known host"
8. 8.- Enter hostname and paste fingerprint

Solution B: Use SSH in pipeline:

pipelines:
  default:
    - step:
        name: Deploy
        script:
          - ssh $DEPLOY_USER@$DEPLOY_HOST 'cd /var/www && ./deploy.sh'

The SSH key is automatically available at ~/.ssh/id_rsa.

Solution C: Test SSH connection:

- step:
    name: Test SSH
    script:
      - ssh -Tv $DEPLOY_USER@$DEPLOY_HOST

Fix 5: Environment Variable Issues

Variables not available or wrong values:

$MY_VAR prints empty
variable substitution not working

Solution A: Define variables correctly:

```yaml # Pipeline-level variables pipelines: default: - step: script: - echo $MY_VAR variables: MY_VAR: 'value'

# Or use Repository/Project variables # Go to Repository Settings → Pipelines → Environment variables ```

Solution B: Use secure variables:

For secrets, use secured variables:

1. 1.Go to Repository Settings → Pipelines → Environment variables
2. 2.Click "Add variable"
3. 3.Enter name and value
4. 4.Check "Secured" checkbox

Secured variables are masked in logs.

Solution C: Access variables:

script:
  - echo "Branch: $BITBUCKET_BRANCH"
  - echo "Commit: $BITBUCKET_COMMIT"
  - echo "Repo: $BITBUCKET_REPO_SLUG"
  - echo "Workspace: $BITBUCKET_WORKSPACE"

Important: Use secured variables carefully:

```yaml # WRONG - secured variables are masked, this will show *** in logs - echo $API_KEY

# CORRECT - use in commands but don't echo - curl -H "Authorization: Bearer $API_KEY" https://api.example.com ```

Fix 6: Timeout Errors

Pipelines exceed the time limit:

Build exceeded maximum allowed runtime

Cause: Bitbucket has pipeline time limits based on your plan.

Solution A: Optimize pipeline:

```yaml # Reduce what runs pipelines: default: - step: name: Build max-time: 10 # Limit this step to 10 minutes script: - npm ci # Use ci instead of install (faster) - npm run build

# Cache dependencies - step: name: Build caches: - node script: - npm ci - npm run build

# Define caches definitions: caches: node: node_modules ```

Solution B: Split into parallel steps:

pipelines:
  default:
    - parallel:
        - step:
            name: Unit Tests
            script:
              - npm run test:unit
        - step:
            name: Integration Tests
            script:
              - npm run test:integration
    - step:
        name: Deploy
        script:
          - ./deploy.sh

Solution C: Use artifacts to pass data:

```yaml pipelines: default: - step: name: Build script: - npm run build artifacts: - dist/** # Pass to next step

• step:
• name: Deploy
• script:
• - ls dist/ # Artifacts are available
• - ./deploy.sh
• `

Fix 7: Permission Errors in Container

Scripts fail with permission denied:

EACCES: permission denied
chmod: changing permissions... Operation not permitted

Cause: Docker containers run as non-root user.

Solution:

- step:
    name: Build
    script:
      - chmod +x ./scripts/*.sh  # Make scripts executable
      - ./scripts/build.sh

For npm:

- step:
    name: Build
    script:
      - npm config set cache /tmp/npm-cache  # Avoid permission issues
      - npm ci

For global installs:

```yaml # WRONG - may fail due to permissions - npm install -g some-package

# CORRECT - use local install - npm install some-package - npx some-package # Use npx ```

Fix 8: Network and Connectivity Issues

Can't reach external services:

curl: Failed to connect to host
npm ERR! network timeout

Cause: Network restrictions in Docker container.

Solution A: Test connectivity:

- step:
    name: Debug Network
    script:
      - curl -I https://registry.npmjs.org
      - ping -c 3 google.com || true

Solution B: Increase timeouts:

- step:
    name: Install Dependencies
    script:
      - npm ci --fetch-timeout=600000

Solution C: Use internal mirrors:

- step:
    name: Install
    script:
      - npm config set registry https://npm.company.com
      - npm ci

Fix 9: Branch-Specific Pipeline Issues

Pipelines not running for specific branches.

Symptoms: - Pipeline doesn't trigger - Wrong pipeline runs - Custom branches ignored

Solution:

```yaml pipelines: default: # Runs for all branches not specified below - step: script: - echo "Default pipeline"

branches: main: # Only for main - step: script: - ./deploy-production.sh

develop: # Only for develop - step: script: - ./deploy-dev.sh

feature/*: # For branches starting with feature/ - step: script: - npm test

tags: v*: - step: script: - ./release.sh

pull-requests: '**': # For all PRs - step: script: - npm test ```

Fix 10: Service Container Issues

Running services like databases in pipelines:

Connection refused to database
Service container not starting

Solution:

```yaml pipelines: default: - step: name: Test services: - postgres - redis script: - npm install - npm test

definitions: services: postgres: image: postgres:15 environment: POSTGRES_DB: test POSTGRES_USER: test POSTGRES_PASSWORD: test

redis: image: redis:7

docker: image: docker:dind ```

Connection to services:

script:
  - PGHOST=localhost PGUSER=test PGPASSWORD=test PGDATABASE=test npm test

Note: Services run as separate containers accessible at localhost.

Quick Reference: Bitbucket Pipeline Errors

Debugging Commands

Add to your pipeline for debugging:

```yaml - step: name: Debug script: - echo "=== Environment ===" - env | sort

• echo "=== System ==="
• - uname -a

• echo "=== Disk ==="
• - df -h

• echo "=== Network ==="
• - curl -I https://bitbucket.org 2>&1 | head -5

• echo "=== Working Directory ==="
• - pwd
• - ls -la
• `