CircleCI SSH Key Fingerprint Error Fix

In this tutorial, you'll learn about CircleCI SSH Key Fingerprint Error Fix. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Your CircleCI job fails with Error: fingerprint not found or Permission denied (publickey) — the SSH key fingerprint in your .circleci/config.yml doesn't match any key stored in the project settings.

The Problem

# WRONG — using an incorrect or missing fingerprint
version: 2.1
jobs:
  deploy:
    docker:
      - image: cimg/base:2024.01
    steps:
      - add_ssh_keys:
          fingerprints:
            - "aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99"
      - run: ssh -o StrictHostKeyChecking=no user@server.com "deploy.sh"

Error: fingerprint not found

The fingerprint aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99 doesn't exist in the project's SSH keys settings.

Step-by-Step Fix

1. Verify the fingerprint in CircleCI settings

Go to Project Settings > SSH Keys. The fingerprint listed there must match exactly what's in config.yml. Copy the fingerprint from the settings page, not from your local ssh-keygen -lf output.

2. Add the SSH key to CircleCI

# Generate a new deploy key
ssh-keygen -t ed25519 -C "deploy@circleci" -f deploy_key

# Add the public key to the target server
ssh-copy-id -i deploy_key.pub user@server.com

Then paste the private key content into Project Settings > SSH Keys in CircleCI.

3. Use the correct fingerprint format

steps:
  - add_ssh_keys:
      fingerprints:
        - "SHA256:abcdefghijklmnopqrstuvwxyz1234567890"

Modern CircleCI uses SHA256 fingerprints. Check the fingerprint format in your project settings.

4. Add host key verification

steps:
  - add_ssh_keys:
      fingerprints:
        - "SHA256:abcdefghijklmnopqrstuvwxyz1234567890"
  - run: |
      ssh-keyscan github.com >> ~/.ssh/known_hosts
      git push --force git@github.com:my-org/my-repo.git main

Expected output:

✓ SSH key added with fingerprint SHA256:abc...xyz
✓ Connected to server.com
✓ Deployment completed successfully

Prevention Tips

• Copy fingerprints directly from CircleCI project settings
• Use separate deploy keys for different servers
• Use ssh-keyscan to add host keys before connecting
• Test SSH access locally before configuring CircleCI
• Rotate deploy keys regularly for security

Common Mistakes with ssh key

1. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
2. Non-exhaustive pattern matches that compile with warnings then crash at runtime
3. Misunderstanding that String is [Char] with poor performance for large text operations

These mistakes appear frequently in real-world CIRCLECI code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ