act "Platform 'ubuntu-latest' not found" running Actions locally

By Kaveh Alemi·Latchkey

act does not know which container image to use for a runs-on label until you map it. When no mapping exists for ubuntu-latest, act cannot choose an image and stops with "Platform not found".

What this error means

act fails with "Error: Platform 'ubuntu-latest' not found" (or a similar label), usually after you cleared the default mappings or used a custom label.

act

Error: Platform 'ubuntu-latest' not found
Please edit your workflow or add a mapping with -P ubuntu-latest=...

Common causes

No image mapping for the runner label

act maps runs-on labels to Docker images with -P label=image. Without a mapping for ubuntu-latest, it has nothing to run.

A custom or self-hosted label act does not recognize

Labels like self-hosted or a team-specific label have no built-in mapping, so act reports them as not found.

How to fix it

Map the label with -P

Pass a platform mapping so act knows which image backs the label.

Terminal

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Persist the mapping in .actrc

Put default mappings in a .actrc file so every run has them without repeating flags.

.actrc

-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04

How to prevent it

Keep a project .actrc with mappings for every label you use.
Map custom labels explicitly instead of relying on defaults.
Document the images so contributors reproduce the same run.

Frequently asked questions

What causes ""Platform 'ubuntu-latest' not found""?

act maps runs-on labels to Docker images with -P label=image. Without a mapping for ubuntu-latest, it has nothing to run.

How do I fix "Platform 'ubuntu-latest' not found"?