xonecas.io
60255
Zn

Zoea-Nova / files

Zoea-Nova / documentation / current / KNOWN_SERVER_ISSUES.md

4.1 KB
1# Known SpaceMolt Server Issues
2
3This document tracks known issues with upstream APIs (SpaceMolt MCP server, OpenCode Zen). We do not modify or validate external API behavior. Issues are documented here, and we improve prompts, error handling, and workarounds instead.
4
5---
6
7## SpaceMolt MCP Server Issues
8
9### captains_log_add: empty_entry Error
10
11**Issue:** The `captains_log_add` tool returns an `empty_entry` error when:
12- The `entry` field is an empty string
13- The `entry` field is missing
14- The `entry` field contains only whitespace
15
16**Server Response:**
17```json
18{"error":{"code":0,"message":"empty_entry"}}
19```
20
21**Workaround:**
22- System prompt includes explicit examples of correct usage
23- Error messages provide actionable guidance when this error occurs
24
25---
26
27### ~~get_notifications: Missing current_tick Field~~ ✅ RESOLVED
28
29**Status:** ✅ **RESOLVED** in server v0.44.4
30
31**Resolution Date:** 2026-02-06  
32**Server Version:** v0.44.4+
33
34The `get_notifications` tool now correctly returns `current_tick` and `timestamp` fields as expected. This issue was fixed in the server release v0.44.4.
35
36**Updated Response Format (v0.44.4+):**
37```json
38{
39  "count": 0,
40  "current_tick": 42337,
41  "notifications": [],
42  "remaining": 0,
43  "timestamp": 1770338536
44}
45```
46
47**Historical Context:**
48Prior to v0.44.4, the `get_notifications` endpoint did not return tick information, making it impossible for MCP clients to track game time. This was documented in forum thread 5e7fa591c8bea87a447864b0e77846d0.
49
50**Release Notes (v0.44.4):**
51> "FIX: get_notifications JSON-RPC handler now actually returns current_tick and timestamp fields"
52> "The v0.44.3 fix only added the buildNotificationsResponse helper but the real handler path never called it"
53
54**Impact on Zoea Nova:**
55- Tick extraction now works correctly via `findCurrentTick()`
56- TUI displays actual game tick instead of 0
57- No code changes were required (extraction logic was already correct)
58
59For historical investigation details, see:
60- `documentation/investigations/GET_NOTIFICATIONS_API_INVESTIGATION.md`
61- `documentation/investigations/TICK_INVESTIGATION_FINDINGS.md`
62
63---
64
65## OpenCode Zen API Issues
66
67### OpenCode Zen: System-Only Message Crash
68
69**Issue:** The OpenCode Zen API returns a 500 Internal Server Error when request messages contain ONLY system messages (no user or assistant turns).
70
71**Server Response:**
72```json
73{
74  "type": "error",
75  "error": {
76    "type": "error",
77    "message": "Cannot read properties of undefined (reading 'prompt_tokens')"
78  }
79}
80```
81
82**Root Cause:**
83OpenCode Zen's token counting logic fails when response metadata is missing or in unexpected format. The API attempts to read token counts from an undefined object, indicating an unhandled null/undefined case in their response parsing.
84
85**Related Issue:**
86OpenCode GitHub Issue #8228: Similar token counting crash with Gemini models
87- URL: https://github.com/anomalyco/opencode/issues/8228
88- Error: `"Cannot read properties of undefined (reading 'promptTokenCount')"`
89- Status: OPEN (as of 2026-02-07)
90
91**Workaround:**
92Zoea Nova implements fallback logic in `internal/provider/openai_common.go`:
93- Detects system-only message arrays
94- Appends fallback user message: `{"role": "user", "content": "Continue."}`
95- Prevents hitting the upstream API bug
96
97**Implementation:**
98```go
99// If only system messages remain, add a dummy user message
100if allMessagesAreSystem {
101    messages = append(messages, openAIMessage{
102        Role:    "user",
103        Content: "Continue.",
104    })
105}
106```
107
108**Status:** ✅ **WORKAROUND IMPLEMENTED**
109
110**Resolution Date:** 2026-02-07  
111**Implementation:** Commit `9348f50` - fix: improve system message merging to preserve conversation
112
113**Impact on Zoea Nova:**
114- OpenCode Zen provider sends valid API requests
115- Conversation history preserved correctly
116- Message validation prevents invalid API calls
117- Provider coverage: 87.0%
118
119**Monitoring:**
120- Watch OpenCode issue tracker for upstream fix
121- Keep workaround in place until server-side bug is resolved
122- No Zoea Nova code changes needed if upstream fixes issue
123
124For implementation details, see:
125- `documentation/investigations/OPENCODE_ZEN_BUG_VERDICT_2026-02-06.md`
126- `documentation/reports/OPENCODE_ZEN_FIX_2026-02-07.md`