Falz Docs

Troubleshooting

Start by increasing log detail:

falz -v build
falz -vv build
falz -vvv build

A source file produces no output

  1. Run falz config and confirm layout is not empty.
  2. Check that a matching layout exists in .falz/schemes/<source-dir>/ or a parent.
  3. Check the <Content src> pattern. It is evaluated relative to each source directory.
  4. Check ignore and the automatic output/.falz ignores.
  5. If it uses a custom pipe, add that name to pipes.
  6. Run falz graph > graph.graphml. If the entry is absent, the problem is scanning/layout matching, not transformation.

See How it works and layout resolution.

A custom pipe is not found

  • Its directory must be .falz/pipes/<name>/.
  • Its config.yaml must have the same useful name.
  • The name must be listed in project pipes.
  • The layout's pipe attribute must match exactly.
  • Restart a one-shot command. In watch mode, check reload errors with -vv.

An npm import does not bundle

Run installation in the pipe directory:

cd .falz/pipes/my-pipe
npm install

Then check whether the package depends on Node built-ins, native addons, or asynchronous host behavior. Falz is not a full Node runtime. Shared dependencies belong in .falz/pipes/shared/node_modules.

Set debug: true in the pipe's own config.yaml to inspect pipeline.dbg.js. This is the bundled program Falz executes, so it can reveal a surprising import or transpilation result.

A build was unexpectedly skipped or rebuilt

Start with a forced run that bypasses artifact caching:

falz -vv build --force --disable-cache

This schedules every discovered entry and executes every transform. If the result is now correct, compare the normal run's dependency inputs:

  • source content;
  • selected pipe and bundled npm dependencies;
  • layout, template, and fragments;
  • <Var> values;
  • KV namespaces listed in contract.consumes.

Use force_hash: true when an external tool may change file contents while preserving both size and modification time. This forces Falz to read files when calculating hashes. Use build --force when hashes are correct but every entry should be processed anyway.

falz graph > graph.graphml helps verify that the expected entry and dependency edges exist. For a custom pipe, set debug: true in its own config.yaml to write pipeline.dbg.js beside the pipe.

index() data is missing or stale

A one-shot build does not run indexing:

falz index --force
falz build

Also check:

  • the pipe exports index();
  • the pipe is listed in project pipes;
  • KV keys use namespace:key;
  • written namespaces appear in contract.provides;
  • read namespaces appear in contract.consumes;
  • values are JSON-serializable.

If necessary:

falz clean index
falz index
falz build --force

A changed shared file did not rebuild output

Files read with the pipe fs module are not automatically added as layout dependency nodes. Options include:

  • make the shared file a normal layout fragment/template/asset;
  • index it into a consumed KV namespace;
  • touch or change the source entry;
  • run falz build --force.

The output path is surprising

to paths are relative to the matched entry's directory. For posts/a.md, to="{ALIAS}/index.html" starts under posts/.

Check the placeholders in Layout reference. An empty {ALIAS} means the pipe returned no alias. An [unknown tag ...] string means the placeholder is misspelled.

Old outputs remain

Enable automatic stale cleanup:

build:
  clean: true

Or run:

falz clean orphans output

Use falz clean output only when deleting the whole generated tree is acceptable.

A pipe times out

Increase its own timeout:

transformTimeoutMs: 10000

For HTTP calls, check both http.timeout and the transform timeout. The smaller effective deadline wins. Also check response and cumulative byte limits.

HTTP is blocked

Every destination and redirect target must match http.allowedHosts in that pipe's configuration:

http:
  allowedHosts:
    - api.example.com
    - "api.example.com:8443"
    - "*.example.net"

--trust-pipes only hides a warning; it does not change the allowlist.

Watch server or hot reload does not work

  • --hot-reload requires --serve.
  • Include <script src="/falz-hotreload.js"></script> in the served page.
  • Use --open=false on headless systems.
  • If an explicitly passed port is busy, choose another; explicit --port disables retries.
  • Restart watch after changing server settings.

Reproduce without incremental state

First try a forced uncached build:

falz build --force --disable-cache

For a fully fresh local result:

falz clean all
falz index
falz build

clean all deletes output and both caches. Only use it when that is intended.