# Andriykalashnykov Flight Path Troubleshooting > Troubleshooting - Skill: `tomevault-io/andriykalashnykov-flight-path-troubleshooting` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/andriykalashnykov-flight-path-troubleshooting` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/andriykalashnykov-flight-path-troubleshooting/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/andriykalashnykov-flight-path-troubleshooting --- # 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: [AndriyKalashnykov/flight-path](https://github.com/AndriyKalashnykov/flight-path) — distributed by [TomeVault](https://tomevault.io).