EN Troubleshooting

Troubleshooting

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

Identify the failing layer first: installation, configuration, network, identity, data policy, runtime, client or desktop packaging. Record request IDs and component versions without sharing secrets.

Server and configuration

Symptom	Likely cause/action
forge not found	Check the venv and python -m pip show json-api-forge; use the venv executable directly
0 project / readiness 503	main has no bundled apps; check app root, working directory and manifest
extra_forbidden	Wrong field name or unsupported version; inspect schema reference
Env URL is None/empty	Check $env: syntax, process environment and explicitly empty values
init refuses an existing file	Expected protection; understand rotation before --force
Duplicate route/slug	Resource duplicated across fragments or conflicting prefixes
New JSON not applied	Disabled watcher, invalid candidate, debounce or draining generations
Hook unchanged	Python restart/reload required; JSON watcher is insufficient
DB schema failure	Migration state and create/validate modes
Stale cached data	TTL/stale/invalidation or external database writes

Authentication, API and proxies

Symptom	Check
Bootstrap 401	Was it consumed when the first persistent key was created?
Valid key but 403	Permissions, tenant/owner, correct project, expiry and scopes
HTTPS rejection behind proxy	Is the direct peer actually within trusted CIDRs?
Too many results with invalid filter	v0.5.1 SQL skips unknown/disallowed filters
Cursor 400	Incorrect mode or forbidden offset/sort arguments
POST retry duplicates work	Is the server operation actually idempotent?
RPC 409	Changed fingerprint, rowcount guard or concurrent work
429/503 under load	Separate rate/concurrency budgets, actual IP and capacity

Python SDK

Symptom	Check
Wrong package/import	Distribution json-api-forge-client; import json_api_forge
HTTP URL rejected	Loopback plus explicit opt-in only; remote HTTPS required
Duplicate /api/...	A helper prefix was also added to the base URL
GET operation called as POST	call_operation is a POST helper; use request
No async iter_items	Sync-only in v0.5.1; implement a bounded async loop
ResponseTooLarge	Actual volume, pagination or deliberate limit adjustment
Compressed response rejected	Proxy ignores Accept-Encoding: identity
Unsupported wheel	Reviewed any_lib tag; use source commit/sdist
DDM import failure	Optional extra and compatible YoungLion installation

Editor

Symptom	Check
Control-plane 404	EDITOR_API_ENABLED, runtime and deployment base
App key cannot log in	Separate Editor account/session required
Local validation passes, server rejects	Local structure checks differ from merged semantic validation
Save 409	Stale SHA; reread server state and reconcile edits
Graph save fails	Graph policy/permission; compilation is separate
Branch/Transform cannot compile	Design-only in this version
Imported plugin is inactive	Import does not enable; review Manage plugins
Plugin/Qt load error	Platform, ABI, CPU, library hash and dependencies
Calls unavailable	WSGI limitation, WSS proxy, TURN and server policy
Portable Qt platform error	Incomplete staging/deployment or isolated executable

A useful issue report

Include component, exact version/commit, OS/CPU, Python or Qt kit, command, expected/actual result and a minimal redacted configuration. Request IDs and nonsensitive traceback sections help. Use the channel in SECURITY.md before posting vulnerability details publicly.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/SUPPORT.md
• main/SECURITY.md
• python-library/json_api_forge/client.py
• Editor/QT-CREATOR-BUILD-GUIDE.md

---

English home · All English pages · Version maintenance