Skip to main content

Common Troubleshooting & Quick Fixes

This guide provides instant fixes for common issues encountered during coding, planning, API testing, and mobile automation with PostQode.

1. This Model Is Blocked by Admin Policy​

Symptom​

When sending a message or running a task, PostQode displays:

Error: Model claude-3-7-sonnet is not permitted by your organization's Model Governance policy.

Root Cause​

Your organization administrator has enabled Model Governance restrictions on your team or workspace in app.postqode.ai, whitelisting specific models and blocking others.

Fix​

  1. Open the PostQode model switcher at the top of the chat panel.
  2. Select an approved enterprise model (e.g. gpt-4o, deepseek-r1, or your team's designated default model).
  3. If your team requires access to a restricted model, contact your Organization Admin to update the model allowlist in Model Governance.

2. Temperature & Output Randomness Issues​

Symptom​

The model output is repetitive, produces hallucinations, or fails to adhere strictly to deterministic coding schemas.

Fix​

  1. Open PostQode Settings (gear icon ).
  2. Navigate to Models ➔ Model Configuration ➔ Expand your active provider's parameters.
  3. Locate the Temperature field (note: temperature is a typed numerical input field, no slider is present):
    • For Deterministic Code & API Tests: Type 0.0 (Recommended default).
    • For Architecture & Brainstorming: Type 0.3 – 0.7.
  4. Changes are saved automatically.

3. Provider Rate Limits (HTTP 429 Too Many Requests)​

Symptom​

The model fails mid-task with 429 Rate limit reached for requests per minute (RPM) or tokens per minute (TPM) or HTTP 429 Too Many Requests.

Root Cause​

Third-party providers (Anthropic, OpenAI, DeepSeek, Groq) enforce strict tier-based rate limits on concurrent requests and tokens consumed per minute.

Fix​

  • Use PostQode Gateway Proxy: PostQode Managed Provider automatically routes and load balances requests across enterprise capacity pools with automated prompt caching.
  • Enable Prompt Caching: Ensure prompt caching is active for Anthropic or OpenAI models to dramatically reduce token consumption by up to 90%.
  • Use Dual Mode Routing: In Model Configuration, configure separate models for Plan Mode (e.g. Claude 3.7 Sonnet) and Agent Mode (e.g. DeepSeek R1 or Qwen Coder) to distribute token usage across different providers.
  • Switch to an Alternative Provider: Route traffic temporarily to OpenRouter, Groq, or a local runtime (Ollama / LM Studio) while your primary provider cooldown period expires.

4. Mobile Agent Prerequisites Missing​

Symptom​

When starting Mobile Agent, PostQode reports that Android SDK, Appium, or connected physical devices are not detected.

Fix​

  1. Open PostQode Settings ➔ Pre-requisites ➔ Android tab.
  2. Inspect which items have a red cross:
    • Node.js (v18+): Install from nodejs.org.
    • Appium: Run npm install -g appium in terminal.
    • Java JDK (11+): Ensure JAVA_HOME environment variable is exported in your shell profile.
    • Android SDK Platform Tools: Verify adb is in your system PATH.
  3. Physical Mobile Devices: Ensure Developer Options and USB Debugging are toggled ON and authorized on the physical mobile device you are connecting via USB or Wi-Fi adb. See Mobile Agent Setup.

5. Corrupt Workspace State or Stuck Tasks​

Symptom​

A task hangs, background subagents fail to report, or local state prevents new tasks from executing.

Fix​

  1. Open PostQode Settings ➔ Debug Tools.
  2. Click Reset Workspace State.
  3. Reload the editor window (Cmd+Shift+P / Ctrl+Shift+P ➔ Reload Window).
  4. Your project source code and git history remain completely untouched; only ephemeral task cache is cleared.

6. Duplicate Local and Global Workflow Names​

Symptom​

When a local (workspace-level) workflow and a global workflow share the exact same name, invoking /workflow-name in PostQode chat shows a single entry without clearly indicating whether it is local or global.

Root Cause & Priority Precedence​

Workspace-level workflows take priority over global-level workflows. When workflows at both levels share identical names, PostQode automatically resolves and executes the workspace-level workflow definition.

Example Scenario​

Imagine you have two workflows named deploy:

  1. Global Workflow: Configured in user global settings (~/Documents/PostQode/Workflows/deploy.md) to run standard deployment to a staging server.
  2. Workspace Workflow: Configured in your active project repository (.postqode/workflows/deploy.md) to execute project-specific production deployment.

When you type /deploy in PostQode chat:

  • Executed Workflow: PostQode triggers the project's Workspace Workflow (.postqode/workflows/deploy.md).
  • Overridden Workflow: The Global Workflow is overridden and bypassed due to lower precedence.

Fix​

  • To run the Workspace Workflow: No action needed. The workspace-level workflow is selected by default due to its higher priority.
  • To run the Global Workflow: Rename or delete the matching workspace-level workflow (located in .postqode/workflows/ or workspace settings) so the global workflow can be resolved without collision.
Is this documentation incorrect or incomplete? Report an issue on GitHub