Iwf Guide

Iwf Guide

Markdown source

Troubleshooting

This page collects the failure modes that come up most often while working on Iwf apps.

1. Canonical PostgreSQL Readiness Fails

If devenv up in examples/canonical reports a PostgreSQL readiness failure or postmaster.pid already exists, an earlier process is probably still holding the example data directory.

Check first:

cd examples/canonical
sh scripts/kill-orphans --dry-run

Then clean canonical example services:

sh scripts/kill-orphans --force

Restart:

iwf-ensure-db
devenv up

2. Generated Idris Files Appear Beside .idrx

The build command is writing to the wrong output directory. For the canonical app, generated views should go here:

build/generated/Web/View/*.idr

The schema module should go here:

build/generated/Generated/Schema.idr

Starter apps should write:

build/generated/Main.idr

Fix the tools/idrx.py -o ... path and keep generated files out of source directories.

3. Login Works With Curl But Not Browser

Compare the body. A browser form posts URL-encoded data:

email=jake%40realworld.test&password=password123

The HTTP parser must decode %40 to @ before auth validation. Also check:

  • Content-Type: application/x-www-form-urlencoded
  • HX-Request: true
  • HX-Boosted: true
  • Location or HX-Redirect response headers

4. HTMX Updates Content But Shell Is Stale

Use the right redirect:

  • seeOther for ordinary boosted form/link redirects
  • htmxHardRedirect only when the whole shell must reload

Hard redirects are appropriate for logout, stale shell recovery, organization switching, or deleting the resource that owns the current shell state.

5. Auto Refresh Does Not Update

Check:

  • the direct HTML document includes the Auto Refresh runtime assets for pages that need live updates
  • the app is started with runApp (app "Name" routes |> withAutoRefresh)
  • live regions are registered by the page-level or advanced Auto Refresh API in use
  • custom SQL reads use transactionExecTracked
  • database writes use transactionExecInvalidating with withTransactionWithAutoRefresh
  • same-page mutations return respondNoContent
  • the table being read is tracked or inferred from TypedSQL

6. TypedSQL Cannot Describe SQL

Confirm the module has:

import Generated.Schema

Confirm PostgreSQL is running and the compiler sees a database URL:

export DATABASE_URL='postgres://user:password@127.0.0.1:5432/app_development'

If the describe database should be built from the current schema file, set:

export IWF_TYPEDSQL_SCHEMA="$PWD/Application/Schema.sql"

If you are outside the Iwf repository, also set IWF_SOURCE or IWF_TYPEDSQL_DESCRIBE so the macro can find the describe helper.

For source-localized failures, run:

iwf check

7. Port Already In Use

Find the process:

lsof -nP -iTCP:8082 -sTCP:LISTEN

For the canonical example, prefer the cleanup script instead of manually killing random processes:

cd examples/canonical
sh scripts/kill-orphans --dry-run
sh scripts/kill-orphans --force

8. Static Assets Look Stale

If framework assets or app static assets look stale:

  • rebuild the app
  • confirm fingerprintedStaticRoutes are mounted when using fingerprinted hrefs
  • include devAssetRefreshScript from an app-level withPageLayout during local work
  • confirm the browser is loading from /__iwf/assets for framework assets

9. OpenAPI Route Missing

Only documented routes appear in the document. Confirm the route is built from a documented action and is included in the route list passed to:

swaggerUiRoutes "/docs" apiInfo appRoutes

Use undocumentedRoute only for internal endpoints.

Next

Return to Getting Started With Iwf.