GitHub Actions "artifact name is not valid" (invalid characters)

Artifact names cannot contain certain characters (such as : / \ < > | * ? and double quotes). A name built from a branch, ref, or matrix value often includes one of these and is rejected.

What this error means

The upload-artifact step fails with "Artifact name is not valid" and lists the forbidden characters, usually when the name is interpolated from a ref or matrix value.

github-actions

Error: The artifact name is not valid: build/feature:x. Contains the following character: Colon :

Common causes

Forbidden characters from interpolation

A name composed from a branch (feature/x) or matrix value contains slashes, colons, or other disallowed characters.

Path-like artifact name

The name was set to a path including directory separators, which are not valid in artifact names.

How to fix it

Sanitize the artifact name

Replace forbidden characters (/, :, etc.) with hyphens before use.
Keep names flat - do not embed directory separators.
Build the name from a sanitized variable in a prior step.

.github/workflows/ci.yml

- run: echo "name=build-${{ github.run_id }}" >> "${GITHUB_OUTPUT}"
  id: art
- uses: actions/upload-artifact@v4
  with:
    name: ${{ steps.art.outputs.name }}
    path: dist/

How to prevent it

Sanitize any interpolated artifact name to allowed characters.
Avoid path separators and colons in artifact names.
Derive names from run_id or a slugified value.