# Troubleshooting

Step-by-step fixes for common problems. Each section: **symptom → cause → fix → verify**.

---

## Quick diagnosis

Run these first from your Lambda package directory (where `lamkit.config.*` lives):

```bash
npx lamkit config          # resolved config + env
npx lamkit list            # registered functions
npx lamkit test --dry-run  # no handler execution — checks paths only
```

If `config` or `list` fails, fix config before testing handlers.

---

## `Cannot find module` for handler entry

**Symptom:**

```
Error: Cannot find module '/path/to/dist/handler.js'
```

**Causes:**

1. `entry` points to `dist/` but you have not built yet.
2. Wrong relative path from config file location.
3. Typo in filename (`handler.js` vs `handlers.js`).

**Fix:**

```bash
# TypeScript project
npm run build
ls -la dist/handler.js

# Or point entry at source and use tsx
# entry: './src/handler.ts'
```

**Verify:**

```bash
npx lamkit test --dry-run worker
```

---

## `Cannot find module '../../contracts/abi.json'`

**Symptom:** Handler loads from `dist/` but JSON/ABI files live under `src/`.

**Cause:** Production layout expects sibling folders next to `dist/`; dev layout keeps assets under `src/`.

**Fix — use `assetLinks` in config:**

```js
export default {
  assetLinks: [{ path: 'contracts', target: 'src/contracts' }],
  functions: [
    { name: 'worker', entry: './dist/handler.js', trigger: 'sqs' },
  ],
};
```

Lamkit creates `contracts → src/contracts` before invoke if `contracts/` does not exist.

**Verify:**

```bash
ls -la contracts    # should be a symlink
npx lamkit test worker
```

**Manual alternative:**

```bash
ln -s src/contracts contracts
```

---

## Wrong or missing environment variables

**Symptom:** Handler works in AWS but fails locally with `undefined` env, connection errors, or wrong region.

**Causes:**

1. `.env` not in the directory you run from.
2. Monorepo: secrets in root `.env`, but lamkit loads only cwd `.env`.
3. Variable names differ between `.env` and handler (`APP_DB_HOST` vs `DB_HOST`).

**Fix — `loadProjectEnv` at top of config:**

```js
import { loadProjectEnv } from 'aws-lambda-devkit';

loadProjectEnv({
  files: ['../../.env'],   // paths relative to config file
  skipDotenv: true,        // do not also load ./.env
  aliases: {
    APP_DB_HOST: 'DB_HOST',
    APP_DB_NAME: 'DB_NAME',
  },
});
```

**Verify:**

```bash
npx lamkit config | grep -E 'DB_|AWS_'
npx lamkit test worker --env LOG_LEVEL=debug
```

**Per-run override without editing files:**

```bash
npx lamkit test worker --env DB_HOST=localhost --data '{}'
```

---

## `lamkit: command not found`

**Symptom:** Shell cannot find `lamkit` after `npm install`.

**Fix:** Use `npx` or an npm script:

```bash
npx lamkit test
# or in package.json:
# "test:lambda": "lamkit test"
```

Install as dev dependency in the **same package** as your config:

```bash
npm install -D aws-lambda-devkit
```

---

## Config file not found

**Symptom:**

```
No lamkit.config.js / .mjs / .ts found
```

**Fix:**

```bash
npx lamkit init
# creates lamkit.config.js + sample handler + events/
```

Supported names: `lamkit.config.js`, `lamkit.config.mjs`, `lamkit.config.ts`, `lamkit.config.cjs`.

Run commands from the directory that contains the config (or pass `--config path/to/lamkit.config.mjs` if your CLI supports it — check `lamkit test --help`).

---

## Handler throws but AWS “works”

**Symptom:** Local test fails; deployed Lambda succeeds with same payload.

**Checklist:**

| Check | What to do |
|-------|------------|
| Event shape | Compare `--event` file vs built event: `lamkit test --dry-run` shows trigger |
| Batch size | AWS may send multiple `Records`; test with `--batch-size 3` |
| Env / secrets | `lamkit config` — compare to Lambda console env |
| IAM / network | Local code may reach RDS/VPC; Lambda uses VPC config |
| Time / IDs | Payload uses real DB IDs in prod, fake IDs locally |

**Capture production event:**

1. Log full `event` in Lambda (temporarily).
2. Save to `events/prod-sample.json`.
3. `npx lamkit test --event events/prod-sample.json`

---

## SQS `listen` receives nothing

**Symptom:** `lamkit listen worker` runs but no messages processed.

**Causes:**

1. Wrong `queueUrl` in config or `.env`.
2. Message sent to a different queue/region/account.
3. Deployed Lambda still consuming messages (race).
4. Empty queue.

**Fix:**

```bash
# Confirm URL
npx lamkit config

# Send then listen (one-shot)
npx lamkit send sqs worker --data '{"ping":true}'
npx lamkit listen worker --once --expect-messages
```

**AWS CLI cross-check:**

```bash
aws sqs get-queue-attributes \
  --queue-url "$WORKER_QUEUE_URL" \
  --attribute-names ApproximateNumberOfMessages
```

**Safety:** Pause Lambda event source mapping on dev queues while using `listen`.

---

## `send sqs` / `send sns` fails with credentials

**Symptom:**

```
CredentialsProviderError / UnrecognizedClientException
```

**Fix:**

```env
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
# Optional for LocalStack / custom gateway:
# AWS_ENDPOINT_URL=http://localhost:4566
```

Install peer:

```bash
npm install -D @aws-sdk/client-sqs
# and/or
npm install -D @aws-sdk/client-sns
```

**Verify:**

```bash
aws sts get-caller-identity
npx lamkit send sqs worker --data '{"test":true}'
```

---

## FIFO queue errors

**Symptom:**

```
MissingParameter: The request must contain the parameter MessageGroupId
```

**Cause:** Standard send flags used against a `.fifo` queue.

**Fix:** Lamkit auto-sets group/dedup IDs when queue URL ends with `.fifo`. Ensure `queueUrl` in config is the full FIFO URL.

```bash
npx lamkit send sqs worker --data '{"orderId":"1"}'
```

---

## TypeScript: `Unexpected token` or import errors

**Symptom:** Parsing error when `entry` is `.ts`.

**Fix:**

```bash
npm install -D tsx
# entry: './src/handler.ts'
npx lamkit test
```

Or build first and point `entry` at `./dist/handler.js`.

---

## `strict-batch` exits 1 unexpectedly

**Symptom:** Test fails with `--strict-batch` but handler “looks fine”.

**Cause:** Handler returns `batchItemFailures` for one or more records (correct SQS partial failure response).

**Verify:**

```bash
npx lamkit test worker --data '[{"id":"1"},{"id":"2"}]' 
# without --strict-batch — inspect returned batchItemFailures in output
```

Use `--strict-batch` only when you want CI to fail on any partial failure.

---

## Stale code after edits

**Symptom:** You changed handler but test runs old logic.

**Fix:**

```bash
npx lamkit test worker --reload --data '{}'
```

Or rebuild for `dist/`:

```bash
npm run build && npx lamkit test worker
```

---

## `assetLinks` did not create symlink

**Symptom:** Link missing; still get module not found.

**Causes:**

1. `path` already exists as a real directory (Lamkit does not overwrite).
2. `target` path wrong relative to project root.

**Fix:**

```bash
rm -rf contracts          # only if safe — not production data
npx lamkit test --dry-run # triggers asset link setup
ls -la contracts
```

Check `target` exists:

```bash
ls -la src/contracts
```

---

## Custom endpoint hits real AWS (or vice versa)

**Symptom:** `AWS_ENDPOINT_URL` set but SDK calls `amazonaws.com`.

**Cause:** `loadProjectEnv()` strips custom endpoints when it detects real `AKIA*` access keys (safety default).

**Fix:**

```js
loadProjectEnv({
  stripCustomEndpointForRealAws: false,
});
```

Or use test credentials / LocalStack keys with endpoint URL.

---

## Debug checklist (printable)

```
[ ] cd to directory with lamkit.config.*
[ ] npm install && npm run build (if using dist/)
[ ] npx lamkit list
[ ] npx lamkit config
[ ] npx lamkit test --dry-run
[ ] npx lamkit test --data '{...}' or --event file.json
[ ] Compare env to Lambda console
[ ] For real queue: send + listen --once --expect-messages
```

---

## Performance tips

Local dev speed is usually dominated by your handler and module load time. These lamkit options reduce toolkit overhead:

### Use compiled JavaScript handlers

Point `entry` at `dist/handler.js` (or run `npm run build` before testing). TypeScript entries (`./src/handler.ts`) require the optional `tsx` peer and transpile on each cold load.

```js
// Faster for tight loops
entry: './dist/handler.js',
```

### Faster `lamkit listen`

| Flag / config | Effect |
|---------------|--------|
| `--raw-logs` | Skips console capture during invoke (handler logs go straight to stdout) |
| `--no-extend-visibility` | Skips visibility heartbeat API calls |
| Default batch invoke | One handler call per poll batch (avoid `--no-batch-invoke`) |
| `aws.attributeNames` / `aws.messageAttributeNames` | Request fewer SQS attributes per poll |

Example minimal SQS poll payload in config:

```js
aws: {
  queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789012/my-queue',
  attributeNames: [],
  messageAttributeNames: [],
},
```

### Faster `lamkit test --all`

Run functions concurrently when you do not need per-function `--env` overrides:

```bash
npx lamkit test --all --parallel
```

`--parallel` is ignored when `--env`, `--reload`, `--cold`, or `--inspect` is set.

### Config caching

lamkit caches parsed config by file modification time. Use `--reload-config` after editing `lamkit.config.*` in a long-lived process.

---

## Still stuck?

1. Minimal repro: one handler, one `test.data`, no AWS calls.
2. Add `console.log(JSON.stringify(event, null, 2))` at handler start.
3. Compare with [Getting started](getting-started.md) and matching [Recipe](recipes.md).

Report issues with: lamkit version (`npx lamkit --version`), config (redact secrets), command line, and full error stack.
