Skip to content
CEagle

Troubleshooting

Every build error, what actually causes it, and the fastest way to confirm it.

Start with the build log. It is on the build page, truncated at 24 KiB, and it carries both the error and whatever the command printed.

Nothing happens when I push#

Build on push is offmost common

The webhook is still received and still records the commit; it just does not queue a build. Turn it back on from the Flight page.

You pushed a branch that is not tracked

Only the tracked branch builds. Check which branch the source names, and repoint it if needed.

The repository went private

Flight refuses the moment the repository event lands, and the source says so. Make it public again and press re-check.

The project is archived

A webhook for an archived project is acknowledged and ignored. Restore the project.

The installation was removed

If the GitHub App was uninstalled or lost access to the repository, the source stops being buildable. Reinstall it, then refresh the installation from the console.

The build failed#

the repository has no .ceagle-flight file#

The manifest is not where this project looks for it, is misspelled, or is on a different branch from the one being built. The leading dot is part of the name.

The Flight page names the manifest the project builds, under Manifest. That is the repository root for most projects, and a manifest path for a project that shares its repository with another.

git ls-tree -r --name-only origin/main | grep ceagle

the .ceagle-flight file is not valid TOML#

A syntax error. The usual causes are an unquoted string, a multi-line string that is not closed, and a smart quote pasted from somewhere else.

python3 -c "import tomllib,sys; tomllib.load(open('.ceagle-flight','rb'))"

the build produced no matching artifact#

The output pattern matched nothing. Either the build did not write what you think, or the path is wrong.

  1. Build in a fresh clone

    git clone --depth 1 --branch main <url> /tmp/check && cd /tmp/check && make

  2. List what appeared

    find . -name "*.8xp" -o -name "*.8xv"

  3. Make the manifest match

    Remember that the toolchain names the file after the NAME variable in your Makefile, not after the repository.

the output pattern matched more than one file#

Narrow the glob. This most often happens when bin/ is committed, or when the build writes both a compressed and an uncompressed artifact. Add bin/ to .gitignore and name the file exactly.

the artifact is larger than a calculator variable#

The program does not fit. Turn compression on in the Makefile, or move data into an appvar that the program reads at runtime.

the build command failed#

A compiler or linker error. It would fail on your machine too, with two exceptions worth ruling out:

It needs the network

A download, a clone, or a package manager. The container has none.

It needs a file that is not committed

Check your .gitignore. Building in a fresh clone finds this immediately.

the build timed out#

The wall clock ran out. Raise the timeout in the manifest, up to 30 minutes, and check that nothing in the build is waiting on input or on a network call that will never answer.

Library builds#

a libify library build writes its own command#

Remove the build command. In libify mode Flight writes the invocation itself, and a command that never ran would be very hard to notice, so it is an error rather than a silent no-op.

a custom library build needs a [build] command#

The opposite. In custom mode there is nothing to generate, so you have to say what to run.

appvar and stub are only read for a custom build#

You set one of those alongside libify mode. A libify build always writes bin/NAME.8xv and bin/NAME.lib, so a path that said otherwise would be ignored.

ce-libify produced no .lib stub next to the appvar#

The appvar exists and the stub does not. In custom mode, either your build did not write it or the path is wrong. If the library genuinely ships no stub, say so explicitly:

stub = ""

a header the manifest names is missing from the build#

One of the header paths does not exist when the command finishes. Paths are relative to the manifest's own directory, and a generated header has to have been generated by then.

two [library] headers share a file name#

The developer archive is flat, so gfx/util.h and net/util.h would overwrite one another. Rename one, or ship only the one callers need.

Publishing#

409 project_disabled#

The project is archived. Restore it.

409 language_set#

You tried to change a project's language. It is fixed once set.

403 on connecting a source#

Either Flight is not currently accepting that language, or the GitHub installation is not one this account owns.

429 too_many_requests#

Writes, uploads and the webhook each have their own budget. Back off and retry.

Rate limits

The budgets, and how they are counted.

Read on

Still stuck#

  1. Read the whole log

    Download it from the log viewer rather than reading the tail. The real error is often above the last line.

  2. Reproduce in a fresh clone

    With no network, if you can. That is the environment Flight has.

  3. Compare against the served example

    curl -s "https://roost.ceagle.cc/api/v1/manifest?language=lib&mode=libify"
CEagle documentation