badges/shields · error · NotFound

not a regular file

Error message

not a regular file

What it means

The GitHub size service fetches metadata for a repository path and renders its file size. The GitHub contents API returns an array when the path is a directory, so the service uses `Array.isArray(body)` to detect directories and throws `NotFound` with 'not a regular file'. Only single-file paths can be sized.

Source

Thrown at services/github/github-size.service.js:67

      return this._requestJson({
        url: `/repos/${user}/${repo}/contents/${path}?ref=${branch}`,
        schema,
        httpErrors: httpErrorsFor('repo, branch or file not found'),
      })
    } else {
      return this._requestJson({
        url: `/repos/${user}/${repo}/contents/${path}`,
        schema,
        httpErrors: httpErrorsFor('repo or file not found'),
      })
    }
  }

  async handle({ user, repo, path }, queryParams) {
    const branch = queryParams.branch
    const body = await this.fetch({ user, repo, path, branch })
    if (Array.isArray(body)) {
      throw new NotFound({ prettyMessage: 'not a regular file' })
    }
    return renderSizeBadge(body.size, 'iec')
  }
}

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Include the full file path (with filename) in the badge URL, e.g. path=src/index.js not path=src
  2. Verify on GitHub that the path is a regular file, not a directory
  3. Correct typos in the path parameter

Example fix

// before
/badge/size/user/repo/src   -> not a regular file
// after
/badge/size/user/repo/src/index.js
Defensive patterns

Strategy: type-guard

Validate before calling

const res = await fetch(`https://api.github.com/repos/${user}/${repo}/contents/${path}`)
const body = await res.json()
if (Array.isArray(body)) throw new Error(`${path} is a directory, not a file`)

Type guard

const isFileEntry = (body) => body != null && !Array.isArray(body) && body.type === 'file'

Try / catch

try {
  await fetchSizeBadge(user, repo, path)
} catch (e) {
  if (e.message === 'not a regular file') return 'n/a'
  throw e
}

Prevention

When it happens

Trigger: Requesting a size badge with a `path` that resolves to a directory (GitHub returns a JSON array of contents entries) instead of a single file; empty directory also yields an array.

Common situations: Path typo pointing at a folder; user forgets to include the filename in the path; path points at repo root; intended file was replaced by a directory of the same conceptual name.

Related errors

AI-assisted analysis of badges/shields@766fd8bc89 (2026-08-30). Data as JSON: /api/errors/ae368f9cf2ddaf6d. Report an issue: GitHub.