GitHub Actions Artifact Has Unexpected Paths or Flattened Structure

An uploaded artifact has a different folder layout than expected because upload-artifact strips the least common ancestor of the matched paths, so the archive root may not be what you assumed.

What this error means

After download, files are at a different depth than in the workspace - a leading directory is missing or multiple inputs collapsed into one level - breaking scripts that expect a specific layout.

path: |
  build/output/app
  build/output/meta.json
# common ancestor build/output is stripped; archive root is app + meta.json

Common causes

Least common ancestor stripped

upload-artifact removes the shared parent directory of all matched files, so the archive starts below that common path, not at the workspace root.

Multiple unrelated globs flatten

Mixing paths with different roots changes the common ancestor and can place files at an unexpected level on download.

How to fix it

Control the root with a single base path

Upload from a single base directory so the structure under it is preserved predictably.

- uses: actions/upload-artifact@v4
  with:
    name: build
    path: build/output    # whole dir; structure under it is kept

Adjust expectations or restructure

1. Account for the stripped common ancestor when reading the downloaded artifact.
2. Stage files into one directory before uploading to fix the root.
3. Avoid mixing globs with different parents in a single upload.

How to prevent it

• Upload from a single base directory to keep a predictable layout.
• Stage outputs into one folder before upload when structure matters.
• Account for the least-common-ancestor stripping in consumers.

Related guides