Troubleshooting

Each entry below is headed by the message Fortly actually shows. Where a message includes your own values, such as a project name or a count, … stands in for them. API errors arrive as JSON in the form {"error": "…"}. Deploy and build messages also appear in the project's log.

Search this page for a few words of your message with Ctrl F or ⌘F.

Deploys

"That archive could not be unpacked: the archive contains a path that escapes the project: …"

An entry in your archive has a path that would land outside the project directory, such as ../config or an absolute path. Fortly refuses the whole archive instead of unpacking it. Build the archive from inside the directory you want to deploy:

tar -C ./build -czf release.tgz .

Symbolic links and hard links in an archive are skipped, not followed, so a release cannot rely on them.

"that upload has more than 50000 files" or "that upload expands to more than 2 GB"

A release can contain at most 50,000 files and unpack to at most 2 GB. Leave out what the release does not need to run, such as test fixtures, caches and source maps. If node_modules is the bulk of it, deploy without it and let the build install dependencies. See builds.

The upload is refused with 413

The archive itself is over 256 MB, before decompression. Reduce it the same way as above.

"that archive has no files in it"

The archive was empty, or it contained only directories. Check the path you passed to tar -C, and that the upload sends the file's bytes. With curl, that is --data-binary @release.tgz.

"Deploy refused: this project has no start command yet, and what was deployed is … — send one as x-fortly-cmd"

Fortly could not work out how to start what you deployed, and the project has no start command saved from an earlier release. Send one with the deploy:

curl -X POST https://api.fortly.com/projects/my-app-ada/deploys \
  -H "Authorization: Bearer $FORTLY_TOKEN" \
  -H "x-fortly-cmd: node server.js" \
  --data-binary @release.tgz

"a release is already being built for this project — wait for it to finish"

The log says "Another release is already building for this project." Only one build runs per project at a time. Wait for the current one to finish, then deploy again.

"Deploy failed. The release that was already live is still live."

The build did not succeed. Nothing changed for your visitors, because the release that was live before is still the one being served. The lines just above this one in the project's log say what went wrong. Fix it and deploy again.

"… needs a server to run, and the server frameworks Fortly can build into a Worker today are Next.js and Nuxt."

The release built, but it needs a server process, and Fortly does not run that framework yet. The full message ends with "Your live deployment is unchanged." A project that builds to static files deploys as usual, so check whether your framework has a static export.

"This upload looks like it needs a server, but it wasn't built through Fortly's own build pipeline …"

You uploaded the built output of a server app. Fortly can only run a server app that it built itself. Deploy the project's source instead, as an upload or a linked repository, and Fortly builds it for you.

"that release has been cleaned up and cannot be restored" or "that version cannot be made live"

You tried to roll back to a release that cannot be served. Either its files are gone, because only the most recent releases are kept, or it never finished building. Pick a release that went live from the project's deployments. See releases.

Your project's address

"… has no deployment yet."

The project exists, but nothing has been deployed to it. The address is ready and starts serving as soon as a release goes live. Deploy from a repository or upload a build. See the quickstart.

"no project is served at …"

The hostname you opened does not belong to any project. The message ends with a hint such as projects are served at <project>-<account>.fortly.com. Check the spelling against the address at the top of the project's page in the console. A project's address uses its full name, which is the name you gave it followed by your account name.

Custom domains

"That record is not visible yet. DNS changes can take a few minutes."

Fortly looked up the _fortly. TXT record and did not find it. Most often, the record name was entered in full on a form that adds your domain itself, so the record ended up as _fortly.shop.example.com.example.com. Enter the relative name (_fortly.shop), check it with dig +short TXT _fortly.shop.example.com, and choose Check now again. See names in DNS forms.

"could not ask DNS about _fortly.…"

Fortly could not reach a DNS resolver, so it cannot tell whether your record exists. This is a 502, not a verdict on your records. Try again shortly.

"… is already pointed at a project"

That hostname is already on another project. A hostname belongs to one project at a time. Remove it from the other project first.

"names under fortly.com are given out by Fortly — add a domain you own"

Your project already has a fortly.com address. Custom domains are for names you own.

"this account has … custom domains, which is all … allows."

Your account has used its custom domain allowance, counting every project and every pending domain. Remove one you no longer serve, or add domain capacity. See limits.

"a domain needs at least one dot — for example app.example.com" or "wildcards are not accepted here — add each name you want to serve"

Enter one full hostname. To serve several names, add each one.

The domain shows "Pointed elsewhere" or "The certificate did not issue"

The domain is verified, but its CNAME does not lead to your project, so a certificate cannot be issued for it. Set the CNAME's value to the project's address, then choose Check now. See custom domains.

API tokens and access

"sign in first"

The request had no Authorization header. Send your token as a bearer token:

curl https://api.fortly.com/projects \
  -H "Authorization: Bearer $FORTLY_TOKEN"

"that token is not valid, or has expired"

The token was revoked, expired, or copied incompletely. Check that the value starts with fly_ and has no spaces or line breaks. Then renew it or make a new one under Settings › API tokens. See API tokens.

"no project called …"

No project by that name is visible to your account. API paths use the project's full name, which is the name you gave it followed by your account name, such as shop-ada and not shop. GET /projects lists the full names. The same message comes back for a project that exists on an account you do not belong to.

"the node is not reachable right now"

The API could not reach Fortly's node, so the request never arrived. It is not a problem with your request. Try again in a moment.

Data

"an update needs a filter" or "a delete needs a filter"

An update or delete with no filter would change or remove every row in the table, so it is refused. Add a filter for the rows you mean:

DELETE /v1/sessions?expires_at=lt.2026-01-01

To clear a table on purpose, filter on a condition every row meets, or drop and recreate the table through /sql. See filters.

"only create, alter and drop are accepted here — use /v1/<table> to read and write"

/sql is for schema changes only. Read and write rows through the table routes, which bind every value. See the server API.

"this table is not open for that. Turn it on under the project's API settings."

The request used the publishable key (cvp_…) on a table, or an embedded table, that is not switched on for that operation. Every table starts closed, with read, create, update and delete as separate switches. Turn on the one you need under the project's Data › API tab. See the frontend API.

"send your publishable key as a bearer token" or "that key is not valid for this project"

A request to /_data/ had no key, or a key for a different project, or a key that has since been rotated. Copy the current key from the project's Data › API tab and send it as Authorization: Bearer cvp_….

Importing a database

"that is a binary file, not SQL. …"

You uploaded a database file, such as SQLite, or a custom-format dump. An import takes a SQL script. Export your database as plain SQL, for example with pg_dump --format=plain, and upload that. See importing.

"stopped after … statements. This one was not accepted: …"

PostgreSQL refused one statement in your script. The message quotes the start of that statement and the database's reason. The import runs in one transaction, so nothing from it was applied. Fix or remove that statement and import again.

"only the account owner or an admin can import a database"

Importing runs a whole script against the database, so it needs the owner or admin role. Ask someone with that role to import, or to change your role. See team.

"there was nothing in that file"

The upload was empty. With curl, send the file with --data-binary @dump.sql.

Schedules

"a schedule has five fields — minute hour day month weekday — and this has …"

Fortly accepts five-field cron expressions only. Shortcuts such as @daily are refused. Write @daily as 0 0 * * *.

"weekday: … is not a number" or "minute: … is outside 0-59"

Each field takes numbers, *, lists (1,3), ranges (1-5) and steps (*/15). Names such as MON or JAN are not accepted, so write 1 for Monday or January. The allowed ranges are minute 0–59, hour 0–23, day of month 1–31, month 1–12, and weekday 0–7, where both 0 and 7 mean Sunday. See schedules.

"the path must start with a slash"

A schedule calls a path on your project. Write it as /jobs/cleanup, not jobs/cleanup or a full URL.

Secrets

"… is set by Fortly and cannot be replaced"

PORT, HOST, PATH, FORTLY_API, FORTLY_TOKEN, DATABASE_URL, DATABASE_TRANSACTION_URL and the PG… connection variables are set by Fortly. Choose another name. See environment.

"a name can use capital letters, digits and underscores — for example DATABASE_URL"

Secret names are uppercase, such as STRIPE_KEY, and cannot start with a digit.

Files

Upload refused with 413

One file can be up to 64 MB. See files.

"a file path cannot step outside the project"

The path contains ... Use a path relative to the project's files, such as images/logo.png.

"no such file"

Nothing is stored at that path. File paths are case sensitive. List what is stored with GET /projects/my-app-ada/files, or open the project's Storage tab.

Connected agents

"this agent was not granted …. Reconnect it and approve that permission."

The agent called a tool that needs a permission you did not approve. Revoke it under Settings › Connected agents, connect it again, and approve the permission the message names. See connect an AI agent.

"no project called … in this agent's access"

The project is not among those you approved for this agent, or the name is the label instead of the full name. Ask the agent to call list_projects and use a name from there.