# 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:

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

Then clean canonical example services:

```sh
sh scripts/kill-orphans --force
```

Restart:

```sh
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:

```text
build/generated/Web/View/*.idr
```

The schema module should go here:

```text
build/generated/Generated/Schema.idr
```

Starter apps should write:

```text
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:

```text
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:

```idris
import Generated.Schema
```

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

```sh
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:

```sh
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:

```sh
iwf check
```

## 7. Port Already In Use

Find the process:

```sh
lsof -nP -iTCP:8082 -sTCP:LISTEN
```

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

```sh
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:

```idris
swaggerUiRoutes "/docs" apiInfo appRoutes
```

Use `undocumentedRoute` only for internal endpoints.

## Next

Return to [Getting Started With Iwf](index.md).