Troubleshooting

Missing API key

CLI authenticated workflows, API management endpoints, and MCP tools require a Pagr API key. Use one of these options:

pagr login
pagr login --manual
pagr config set-key pagr_...
export PAGR_API_KEY="pagr_..."

For MCP, pass PAGR_API_KEY through the MCP server environment, a client secret field, or a bearer-token header instead of writing it in a prompt.

Wrong package command

Use the scoped package names:

npm install -g @getpagr/cli
npx -y @getpagr/mcp

Older examples using pagr as the npm package name are outdated. The installed CLI command is still pagr.

Skills page or install command

The public skills docs page is /docs/skills. If an old nested MCP skills link is used anywhere, update it to the top-level skills docs URL.

Install the Pagr skill with:

npx skills add https://github.com/getpagr/skills --skill pagr

The Pagr skill is listed at Skills.sh.

Upload must use HTML content type

The upload API only accepts HTML content types.

Content-Type: text/html; charset=utf-8

If you send JSON to /api/upload, the API returns 415.

File size limits

Anonymous uploads are limited to 1 MB and expire after 24 hours. The live production plan catalog currently uses:

Free: 25 active files, 1 MB per file, 7-day default TTL.
Pro: 500 active files, 25 MB per file, permanent by default.
Team: 1000 active files, 50 MB per file, permanent by default.

If the API returns 413, reduce the HTML file size or upload from an account with a higher limit.

TTL and expiry

Authenticated uploads use the account tier default unless you choose another TTL. Free defaults to 7d; Pro and Team default to never.

pagr upload report.html --ttl never

Valid authenticated TTL values are never, 24h, 7d, 30d, and 1-visit. Free accounts can use 24h and 7d; permanent, 30-day, and read-once pages require Pro or Team.

Anonymous upload expiry and rate limits

Anonymous uploads expire after 24 hours and are rate-limited to 10 uploads per hour per source IP. If you receive 429 Rate limit exceeded, wait for the next hour or create a free account and upload with authentication.

Claim anonymous pages into an account before expiry if they should remain available.

Slug conflicts

Custom slugs must be available and supported by the account plan. If a slug is already taken, use a different slug or let Pagr generate one.

For updates, prefer storing documentId or using CLI metadata injection so automation can update the same document even if its slug changes.

Updates replace the current HTML in place. Pagr does not keep older copies for restore, so keep your source HTML in your own project or repository.

Plan-gated features

Custom slugs, password protection, analytics, read-once pages, and hiding the hosted Pagr banner are plan-gated. API responses include a feature field for some gated errors, such as analytics, passwordProtection, or hideBanner.

Free pages show the hosted on Pagr banner. Pro and Team accounts can hide it per file or from Settings. If a paid subscription becomes inactive, gated features fall back to Free behavior until the account returns to a paid plan.

Browser CSP issues

If browser uploads fail with a Content Security Policy error, confirm the site allows the Worker origin in connect-src.

connect-src 'self' https://app.getpagr.co https://pagr.link https://cloudflareinsights.com

Local development may need a local worker URL such as http://localhost:8787 depending on the environment.

Local worker URL vs production

The production API base URL is https://pagr.link. For local testing, set PAGR_WORKER_URL or WORKER_URL to the local worker origin used by the app you are running.

MCP client cannot find tools

Restart the MCP client after changing its config. Confirm the local command is:

npx -y @getpagr/mcp

For local MCP, ensure the environment contains PAGR_API_KEY.

For remote MCP, configure https://mcp.getpagr.co/mcp and pass one of:

Authorization: Bearer pagr_...
PAGR_API_KEY: pagr_...
X-Pagr-Api-Key: pagr_...
?PAGR_API_KEY=pagr_...

If the remote server returns Missing bearer token, the client is not passing the key to the MCP request.

Smithery auth

The Smithery listing is getpagr/pagr.

npx -y smithery mcp add getpagr/pagr

Smithery requires a Pagr API key for tool execution. If Smithery reports auth or config errors, confirm the configured key starts with pagr_ and has not been rotated.

Quick actions