9. Troubleshooting and glossary
Use the symptom to choose an investigation. Preserve commands, exit codes, and logs; do not turn a failing check into a claimed pass by weakening its requirements.
Common issues
| Symptom | Likely cause | Next step |
|---|---|---|
| dotnet: command not found | SDK directory absent from PATH | Try the absolute SDK path in lesson 1; inspect --info |
| SDK requested by global.json not found | Installed SDK does not satisfy selection | Compare --list-sdks to global.json; human installs a matching SDK |
| Foundry says tests: Extra inputs are not permitted | Older CLI loaded | Use the reviewed preview source path; verify it exists |
| Foundry asks for a signature/denies runtimes.manage | Exact host launch needs owner authorization | Human reviews/signs the launch; do not bypass it |
| Session expired or already active | Session lifecycle conflict | Inspect session metadata and actual worker; renew/end/start through CLI appropriately |
| Connection refused on 5080 | No running/reachable API | Inspect runtime state/logs, port, and actual launch outcome |
| Address already in use | Another process uses the port | Identify its owner before changing/stopping anything |
| Startup migration or SQLite open failure | Path permissions/schema/access issue | Inspect runtime diagnostic and connection string; avoid deleting data to hide it |
| Netlify data-entry buttons are disabled | Expected read-only demo behavior | Browse synthetic records; connect a separately hosted backend before enabling writes |
| Netlify build demands MINIEHR_API_ORIGIN | No backend origin configured | Supply the real public HTTPS backend origin; not a placeholder or localhost |
| API returns 400 | Missing/invalid input | Inspect errors/detail, paired vitals, dates, note length, positive versions |
| API returns 404 | Wrong/missing ID, wrong clinical parent, or invalid GUID route | GET the parent and verify generated IDs |
| API returns 409 | Duplicate MRN, stale version, closed encounter, or SQLite contention | Read current state; decide how to reapply changes |
| Save succeeded but refresh failed | Write committed, follow-up read failed | Refresh saved state; do not resubmit the already-confirmed write |
| dotnet passes but Foundry exits 1 | Known evidence reconciliation gap | Preserve candidate and problems; consult FOUNDRY_GAPS.md |
| Foundry status shows no validation | Known task/workstream display gap | Inspect recorded validation events; absence from display is not proof no run happened |
Read-only database inspection
If the synthetic local database from lesson 1 exists and sqlite3 is installed:
sh
sqlite3 -readonly /private/tmp/miniehr-frontend-synthetic.db '.tables'
sqlite3 -readonly /private/tmp/miniehr-frontend-synthetic.db \
'SELECT MedicalRecordNumber, GivenName, FamilyName, Version FROM Patients;'
sqlite3 -readonly /private/tmp/miniehr-frontend-synthetic.db \
'SELECT Id, IsClosed, ClosedAt, Version FROM Encounters;'Expect Patients, Encounters, Vitals, Notes, and EF's migration history table among the tables. SQL column names correspond to mapped C# properties; JSON uses camelCase. This is supplementary inspection, not a new Foundry test artifact. Do not edit database rows to reopen encounters. To start fresh for another exercise, arrange a new synthetic database path in an owner-reviewed supervised launch; the API does not offer reset/delete.
Where to look when changing something
| Intended change | Read first |
|---|---|
| Patient validation | Patient.cs, Patients.cs, PatientTests.cs |
| HTTP request fields | PatientsController.cs or ClinicalController.cs |
| Clinical write/closure behavior | Encounter.cs and ClinicalStore.cs |
| Database schema | EhrDbContext.cs, frozen migration models, persistence tests |
| Browser forms/messages | app.js, index.html, app.css |
| Netlify proxy | build-netlify.mjs and netlify.toml |
| Engineering policy/evidence | AGENTS.md, .foundry config, docs/foundry reports |
Use the source links in earlier lessons for these files. Request ownership before editing outside your assigned paths. Schema changes need a reviewed migration and upgrade tests, not modifications to a previously applied migration.
Glossary
| Term | Plain meaning |
|---|---|
| API | A program-facing interface; here HTTP routes returning JSON |
| Assembly | A compiled .NET unit, normally a DLL |
| Attribute | Metadata such as Required or Fact interpreted by a framework |
| Candidate | Exact commit/tree proposed for evaluation/integration |
| Cancellation token | Signal requesting that asynchronous work stop |
| Compiler | Tool translating C# into compiled code and reporting diagnostics |
| Concurrency | Overlapping operations that may compete over state |
| Connection string | Settings telling a database provider where/how to connect |
| Controller | Class whose methods handle HTTP routes |
| DbContext | EF's working object for queries, tracking, and saving |
| Dependency injection | Supplying an object's dependencies from registered services |
| Domain | Objects and business rules independent of HTTP/storage mechanics |
| DTO | Data transfer object describing transport input/output |
| Egress | Outbound network access from an execution boundary |
| Encounter | A record of an interaction with a patient |
| Entity | Object with identity and lifecycle persisted by the application |
| Foreign key | Database reference to a parent row |
| GUID | Identifier used for patient/encounter/content IDs |
| Idempotent | Repeating an operation preserves its original effective result |
| Integration test | Test spanning components, such as HTTP plus actual SQLite |
| LINQ | C# query operations over data sources/collections |
| Migration | Versioned change to database schema |
| Middleware | A step in the web request pipeline |
| MRN | Medical record number; a unique synthetic identifier here |
| NuGet | .NET package distribution system |
| Optimistic concurrency | Rejecting writes if the expected version is no longer current |
| Origin | Scheme, host, and port identifying a web origin |
| ORM | Tool mapping objects and database operations; EF Core is used here |
| Pagination | Splitting a collection into pages |
| Primary key | Value uniquely identifying a row |
| Problem Details | Structured HTTP error response |
| Proxy rewrite | Hosting rule forwarding a browser request to another server |
| Rollback | Undoing uncommitted transaction changes |
| Runtime | .NET execution environment; in Foundry, a supervised process record |
| Scope | Lifetime of dependency-injected objects; also the coverage of a validation |
| SDK | Development kit containing compiler and development tools |
| Solution | Group of related .NET projects |
| Static asset | File served directly, such as HTML, CSS, or JavaScript |
| Synthetic data | Invented information representing no real patient |
| Task | C# asynchronous operation; in Foundry, an engineering objective |
| Transaction | Database operation group that commits or rolls back together |
| TRX | Machine-readable .NET test report |
| Unit test | Focused test of behavior without the whole application stack |
| Workstream | Assigned engineering scope with role/ownership |
Final learning check
You should be able to explain how a request reaches the controller, how the domain validates it, how EF persists it, how versions avoid overwrites, why closure is atomic, why the hosted preview needs a backend, and why passing C# tests does not yet establish Foundry acceptance. Revisit the relevant lesson for any unclear step.
Return: Tutorial index.