# Troubleshooting

> >

- **Type:** Skill
- **Install:** `agentstack add skill-andriykalashnykov-flight-path-troubleshooting`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AndriyKalashnykov](https://agentstack.voostack.com/s/andriykalashnykov)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AndriyKalashnykov](https://github.com/AndriyKalashnykov)
- **Source:** https://github.com/AndriyKalashnykov/flight-path/tree/main/.claude/skills/troubleshooting

## Install

```sh
agentstack add skill-andriykalashnykov-flight-path-troubleshooting
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Troubleshooting

## Port 8080 in Use

```bash
lsof -ti:8080 | xargs kill -9
# or
pkill -f "flight-path/server"
```

## API Returns 404

- Health check is `GET /` (not `/health`)
- Calculate is `POST /calculate` (not GET)
- Check Swagger: http://localhost:8080/swagger/index.html

## API Returns 500

- Check server terminal for error logs
- Test with minimal input: `curl -X POST http://localhost:8080/calculate -H 'Content-Type: application/json' -d '[["SFO", "EWR"]]'`
- Verify input format: `[][]string` — each segment must be exactly 2 airport codes

## Swagger Docs Stale

```bash
make api-docs    # Regenerate from annotations
pkill -f server  # Restart server
make run
```

- If generation fails, check Swagger annotation syntax against existing handlers in `internal/handlers/`
- Hard-refresh browser (Ctrl+Shift+R) to clear cached Swagger UI

## Build Fails

```bash
go version                # Must match the `go` directive in go.mod
go mod tidy && make build # Clean up and retry
go clean -cache           # Nuclear option
```

- `make build` depends on `api-docs` (which depends on `deps`), then compiles
- Ensure `GOFLAGS=-mod=mod` is set (Makefile sets this automatically)
- Use `make check` (alias for `make ci`) for the full local pipeline: static-check + test + integration-test + coverage + coverage-check + build + fuzz + deps-prune-check

## `static-check` / `govulncheck` Fails on an Unrelated PR (Go stdlib CVE)

**Symptom:** An open PR that touches no Go code — e.g. a Renovate GitHub Actions
SHA bump — fails the `static-check` job at the `govulncheck` step. Multiple
in-flight PRs fail identically.

**Root cause:** `govulncheck` flags a Go **standard-library** vulnerability
present in the pinned Go patch on `main`. The failure lives in `main`'s
toolchain, not the PR diff, so it surfaces on *every* PR's `static-check`.
This is the "N in-flight PRs failing identically → diagnose `main`, not the
PRs" pattern. It recurs each time a Go patch ships stdlib security fixes.

**Diagnose** — read the actual failing step, don't guess:
```bash
gh run view  --log-failed | grep -A4 'Vulnerability #'
# Look for: "Standard library", "Found in: @goX.Y.Z", "Fixed in: @goX.Y.W"
```

**Fix (real fix — bump Go; NEVER waive a reachable stdlib CVE).** Bump the Go
patch across all three pins in ONE change (mirrors Renovate's "Go toolchain"
group so the managers stay consistent):

| File | Line |
|------|------|
| `go.mod` | `go X.Y.W` |
| `.mise.toml` | `go = "X.Y.W"` |
| `Dockerfile` | `golang:1.26-alpine@sha256:` — refresh so the `docker` job's Trivy scan doesn't ship a binary built against the old stdlib |

Get the new digest and confirm it is the fixed patch *before* editing:
```bash
docker buildx imagetools inspect golang:1.26-alpine --format '{{.Manifest.Digest}}'
docker run --rm golang:1.26-alpine@ go version   # MUST show the fixed patch goX.Y.W
```

Verify locally before pushing (this is the proof, not a hope):
```bash
mise install go@X.Y.W
mise exec -- govulncheck ./...   # must report "No vulnerabilities found"
make static-check                # the full gate that was failing
make check-go-alignment          # go.mod and .mise.toml must agree
```

**The bump is not done at the pins — sweep the docs in the SAME PR.** Prose
docs (`README.md`, `CLAUDE.md`, `specs/`, `docs/ARCHITECTURE.md`, the
`.claude/agents/*.md` and `.claude/skills/*.md` files) are not touched by
Renovate and go stale on merge. Do NOT grep one exact version string — grep the
broad pattern across the whole tree and prove zero stale remain:
```bash
git ls-files | xargs grep -nE 'go ?1\.26|gvm' 2>/dev/null   # inspect every hit
make check-docs-go-version                                   # the drift gate; must pass
```
`check-docs-go-version` runs inside `static-check` and reds CI if any live-state
doc still shows an old Go patch — never declare the bump done until it is green.
Full procedure: the "Bumping the Go version" checklist in the `workflows` skill.

Then PR the fix to `main` (do NOT push onto the Renovate branch — it can
auto-merge from under you). Renovate auto-rebases the in-flight PRs onto the
fix and they go green.

**Why Renovate didn't bump it first:** Go patches ship ~monthly and
`govulncheck` flips red the instant a CVE is disclosed — faster than any
Renovate schedule + CI + automerge cycle, so a manual bump-on-red is the
correct fast path. Additionally, if past Go bumps were applied **manually**
(as stdlib-CVE fires force), Renovate's gomod extraction diverges and the
"Go toolchain" group stops firing. Tell: the Renovate Dependency Dashboard
(issue #8) freezes at an old `go` version and lists deps the repo no longer
has. To re-engage it, tick the rebase/refresh checkbox on the Dashboard to
force a fresh extraction.

## Tests Fail

```bash
go test -v ./...          # Verbose output
go clean -testcache       # Clear cache
go test -race ./...       # Check for races
```

- `make test` runs tests with `TZ="UTC"` and `GOFLAGS=-mod=mod`
- Benchmarks: `go test ./internal/handlers/ -bench=. -benchmem -benchtime=3s`

## E2E Tests Fail

Server must be running first:
```bash
make run &
sleep 3
make e2e
pkill -f server
```

- `make e2e` depends on `deps` (installs Newman if missing)
- Tests live in `test/FlightPath.postman_collection.json`
- CI polls with curl for up to 30 seconds for server startup

## Docker Build Fails

```bash
docker buildx ls                    # Check builder exists
docker buildx create --use --name builder --driver docker-container --bootstrap
make image-build                    # Build locally (single platform, uses buildx)
docker build --no-cache -t flight-path:debug .  # Build without cache
```

- Image: multi-stage Alpine build (`golang:1.26-alpine` -> `alpine:3.23.4`)
- Non-root user: `srvuser:srvgroup` (uid/gid 1000)
- `CGO_ENABLED=0`, platforms: `linux/amd64`, `linux/arm64`, `linux/arm/v7`
- `make image-push` builds then pushes to GHCR (`ghcr.io//flight-path:`); requires `GH_ACCESS_TOKEN`. Multi-arch build + cosign signing happen in the `docker` CI job on tag pushes

## Docker Container: Port Configuration

The container runs fine **without** a `.env` file. `internal/envfile.Load`
treats a missing file as a no-op (returns nil), and `app.Port()` defaults to
`8080` when `SERVER_PORT` is unset — so there is no "crashes without .env"
issue (the in-house `envfile` package replaced `github.com/joho/godotenv`,
which used to `log.Fatal` on a missing file).

To run on a non-default port, set `SERVER_PORT` via `-e` (or an env-file):
```bash
docker run -d -p 9090:9090 -e SERVER_PORT=9090 flight-path:local
```

`make image-run` / `make image-test` handle this automatically — they bind a
free host port and pass `--env-file .env.example`.

## Tool Not Found

```bash
make deps                           # Install all tools
export PATH=$PATH:$(go env GOPATH)/bin  # Ensure tools are on PATH
```

- `newman` requires Node.js — `make deps` provisions Node via mise and installs newman via pnpm (corepack)

## Diagnostic Commands

```bash
ps aux | grep -E "(server|flight-path)"  # Check processes
lsof -i:8080                              # Check port
curl http://localhost:8080/                # Test health
which swag golangci-lint gosec govulncheck gitleaks actionlint newman  # Check tools
go env GOPATH GOROOT                       # Check Go paths
make check                                # Run full pre-commit checklist
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AndriyKalashnykov](https://github.com/AndriyKalashnykov)
- **Source:** [AndriyKalashnykov/flight-path](https://github.com/AndriyKalashnykov/flight-path)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-andriykalashnykov-flight-path-troubleshooting
- Seller: https://agentstack.voostack.com/s/andriykalashnykov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.