Buffaly Logo
Operations

Troubleshooting, logs, validation, and recovery

Use this guide when a Buffaly session, tool, provider, page, or documentation task needs evidence-first diagnosis and safe recovery.

Quick answer

  1. Check logs first: runtime logs live under C:\logs, and Buffaly app runs should start with C:\logs\Buffaly.
  2. Identify the session key and whether it is loaded, running, queued, compacted, or backed by a child session or subagent.
  3. Inspect the relevant source or wiki page before acting, especially safety, session anatomy, long-running work, tools, services, or provider documentation.
  4. Prefer typed Buffaly diagnostics, session status, action search, and service checks before ad hoc shell commands.
  5. Validate with concrete evidence: logs, scoped file paths, route output, git status, commits, and queued/session state.

Who this is for

This page is for technical Buffaly users and operators who need to diagnose common failures without becoming internal runtime maintainers. It focuses on verified checks: where to look, what to ask Buffaly, how to validate results, and how to recover safely.

Older implementation paths may still contain earlier implementation names. In user-facing guidance, say Buffaly agent unless you are naming an implementation path, file, or prototype exactly.

Keep the first pass read-only

Start with evidence, not recovery attempts. Safe first checks include reading logs, inspecting Plan/Scratch/task artifacts, listing session status, checking queued counts, validating file existence, reading source references, and running scoped status commands.

Safe checks

  • Read C:\logs\Buffaly and session artifacts.
  • List loaded tools, queued work, and current status.
  • Verify file paths, routes, and source references.

Stop for confirmation

  • Restarting services, deploying, sending, or submitting forms.
  • Deleting files, clearing credentials, or changing provider settings.
  • Committing changes unless the task already authorizes it.
Diagnose the issue with read-only checks first. If recovery requires a restart, credential change, external send, delete, deploy, or commit, stop and report the evidence before acting.

Key evidence to collect

Logs

Use C:\logs for runtime/application logs and C:\logs\Buffaly first for Buffaly app runs. Logs are useful for startup, worker, provider/auth, service, tool-call, and unexplained UI failures.

Session artifacts

Inspect the session key, Plan.md, Scratch.md, durable task files, session.json, compaction files, backups, queued input count, and child-session relationship.

Typed diagnostics

Use available status and runtime diagnostics before process spelunking. Runtime-reference diagnostics, startup diagnostics, service diagnostics, and queued input endpoints often explain missing tools or stuck work.

Troubleshooting by symptom

Symptom Likely areas Useful verified checks
Tool cannot be found or loaded Action search wording, loaded tool state, entity binding, service registration, startup diagnostics, or projected runtime tool naming. Search candidate actions twice, search target entities, list loaded tools, and check runtime/startup diagnostics before asking the user to choose a tool.
Child session or queued instruction is stuck Parent still running, queued inputs, child status, subagent last error, worker recycle, or lost parent/child session relationship. Check parent and child session keys, queued inputs, last status, last error, Plan, Scratch, task artifacts, and long-running work guidance.
Provider, authentication, or model selection fails Missing provider/model settings, expired or misplaced credentials, unsupported transport, bearer token requirements, or wrong generated JsonWs route. Inspect provider/auth docs, selected provider/model/transport/reasoning, configured secret key, and non-secret log diagnostics. Never echo tokens.
Timeline is noisy or compaction happened Large timeline, archived compaction epochs, old chat relied on instead of task artifacts, or active state not restated after recycle. Re-read Plan, Scratch, task artifacts, changed files, blockers, and the next validation step before continuing.
File, commit, or generated article is missing Wrong root, wrong relative path, untracked file, ignored unrelated changes, leftover artifacts, or incorrect staged files. Validate the absolute path, run scoped git status, check whether the target is already committed, and stage only intentional files.
Web module, UI page, or JsonWs route is missing Missing manifest, disabled module, unresolved assembly/type, absent generated JsonWs artifacts, auth/static asset issues, or source present but deployment not installed. Check the web-module manifest, module catalog snapshot, /api/diagnostics/web-modules, generated JsonWs folder, route, and credentials.
Tool or integration fails after loading Credentials, profiles, base URLs, invalid route/query, missing approval, external availability, or shell fallback hiding typed diagnostics. Identify the integration boundary, required configuration, credential reference, validation step, and relevant non-secret logs before retrying.

Copy-ready troubleshooting prompts

Missing tool

Search candidate actions twice with different wording, search candidate entities for the target service or account, list loaded tools, and report why you selected the next action before calling it. Check startup diagnostics if a projected tool is missing.

Queued or child work

Check the parent session key, child session key, queued inputs, last status, and last error. Summarize what is running, what is queued, and what is blocked before taking another action.

Provider error

Inspect provider and authentication guidance plus the relevant configuration. Do not reveal secret values. Report the provider, model, transport, secret-key reference, and non-secret validation failure.

Compaction or recycle

Re-read Plan, Scratch, and the task artifact. Restate the last completed step, active acceptance criteria, changed files, blockers, and next validation step before editing.

Verification checklist

Before declaring troubleshooting complete, ask for evidence that matches the failing surface.

  • Logs checked: exact directory or log file, especially C:\logs\Buffaly for Buffaly app runs.
  • Source checked: wiki, docs, implementation, or runtime files that support the conclusion.
  • Session checked: session key, status, queued count, child relationship, startup diagnostics, or compaction state.
  • Files checked: exact absolute paths exist when file output was expected.
  • Git checked: scoped status, staged files, commit hash, and changed files.
  • Secrets protected: passwords, tokens, and bearer secrets were not echoed.

Use a recovery loop

  1. Confirm the target repository, project, route, session key, or integration boundary.
  2. Inspect direct evidence from files, logs, command output, route output, or session artifacts.
  3. Make one bounded fix batch, or stop if the next action is destructive or externally visible.
  4. Run validation owned by the changed surface.
  5. If validation fails, preserve the exact failure and change approach instead of repeating the same command.
  6. Commit only the intended files after validation passes and the task authorizes a commit.

Practical examples

Diagnose a missing deployment tool:Search actions with two phrasings, search for the deployment environment entity, list loaded ProtoScript tools, check startup diagnostics, and report the verified blocker before taking action.
Recover a documentation assignment:Validate that the exact wiki source and Razor target exist, check scoped git status for only those paths, run docs checks and build, then stage and commit only the assigned article.
Investigate a provider error safely:Check C:\logs\Buffaly for the latest provider/auth error. Report provider, model, transport, reasoning level, credential reference, and non-secret diagnostic details without revealing the secret value.

Common mistakes

Skipping logs. Logs often separate provider, worker, web-module, and tool-call failures from prompt confusion.

Using shell first. Prefer typed Buffaly tools, service diagnostics, module catalog checks, and session/status APIs where they fit.

Repeating failed calls. If a call produced no new state, inspect diagnostics, logs, source, or entity binding instead.

Ignoring queued work. Check queued state before assuming the agent ignored a follow-up.

Leaking secrets. Use secret keys and user secrets; never paste credentials into troubleshooting summaries.

Committing unrelated files. Always stage only files intentionally changed for the current task.