1====== Calendar Plugin - Debug Instructions ======
2
3===== Debugging Recurring Event Issues =====
4
5If recurring events are not appearing when navigating between months, the JSON event files may be corrupted or malformed. Follow these steps to diagnose the issue.
6
7==== Method 1: Using the Debug Script (Recommended) ====
8
9  - SSH into your server
10  - Navigate to the calendar plugin directory:
11
12<code bash>
13cd /path/to/dokuwiki/lib/plugins/calendar/
14</code>
15
16  - Run the debug script for the month you want to inspect:
17
18<code bash>
19# Check March 2027
20php debug_events.php "" 2027-03
21
22# Check January 2026
23php debug_events.php "" 2026-01
24
25# Check with namespace
26php debug_events.php "team" 2027-03
27</code>
28
29The script will show you:
30  * ✓ If the file exists
31  * ✓ Raw file contents
32  * ✓ JSON validation errors
33  * ✓ All events in the file
34  * ⚠️ Any problems (invalid UTF-8, unexpected fields, corrupted data)
35
36==== Method 2: Manual File Inspection ====
37
38Navigate to your DokuWiki data directory:
39
40<code bash>
41cd /path/to/dokuwiki/data/meta/calendar/
42ls -la
43</code>
44
45You should see JSON files like:
46  * ''2026-01.json'' (January 2026)
47  * ''2026-03.json'' (March 2026)
48  * ''2027-03.json'' (March 2027)
49  * etc.
50
51View the contents of a specific month:
52
53<code bash>
54cat 2027-03.json
55</code>
56
57Or use a text editor:
58
59<code bash>
60nano 2027-03.json
61# or
62vi 2027-03.json
63</code>
64
65==== What Good JSON Looks Like ====
66
67A properly formatted event file should look like this:
68
69<code json>
70{
71    "2027-03-15": [
72        {
73            "id": "abc123-1",
74            "title": "Yearly Event",
75            "time": "",
76            "description": "",
77            "color": "#3498db",
78            "isTask": false,
79            "completed": false,
80            "endDate": "",
81            "recurring": true,
82            "recurringId": "abc123",
83            "created": "2026-01-24 10:30:00"
84        }
85    ],
86    "2027-03-20": [
87        {
88            "id": "xyz789",
89            "title": "Another Event",
90            "time": "14:00",
91            "description": "Meeting notes",
92            "color": "#008800",
93            "isTask": false,
94            "completed": false,
95            "endDate": "",
96            "recurring": false,
97            "created": "2027-03-15 09:00:00"
98        }
99    ]
100}
101</code>
102
103==== Common Problems to Look For ====
104
105=== 1. Truncated/Corrupted File ===
106
107<code json>
108{
109    "2027-03-15": [
110        {
111            "id": "abc123-1",
112            "title": "Yearly
113</code>
114
115**Problem:** File is incomplete, missing closing braces.
116
117**Fix:** Delete the corrupted file and recreate the event.
118
119=== 2. Invalid Characters ===
120
121<code json>
122{"2027-03-15":[{"title":"Test\x00Event"}]}
123</code>
124
125**Problem:** Null bytes or invalid UTF-8 characters.
126
127**Fix:** Edit the file and remove invalid characters, or delete and recreate.
128
129=== 3. Empty or Malformed ===
130
131<code json>
132{}[]
133</code>
134
135**Problem:** Invalid JSON structure.
136
137**Fix:** Delete the file or replace with ''{}''
138
139=== 4. Multiple Root Objects ===
140
141<code json>
142{"2027-03-15":[...]}
143{"2027-03-16":[...]}
144</code>
145
146**Problem:** Two separate JSON objects instead of one merged object.
147
148**Fix:** Manually merge into a single object or delete and recreate events.
149
150==== Browser Console Debugging ====
151
152  - Open your browser's Developer Tools (''F12'')
153  - Go to the **Console** tab
154  - Navigate between months in the calendar
155  - Look for messages like:
156
157<code>
158Month navigation data: {success: true, events: {...}, year: 2027, month: 3}
159Rebuilding calendar for 2027 3 with 1 date entries
160</code>
161
162**Key things to check:**
163  * ''success: true'' - API call worked
164  * ''events: {...}'' - Should contain event data
165  * ''"with X date entries"'' - Should be > 0 if events exist
166
167**If you see "with 0 date entries":**
168  * The JSON file is empty, missing, or corrupted
169  * Check the actual file with the debug script
170
171==== Fixing Corrupted Files ====
172
173=== Option 1: Delete and Recreate ===
174
175<code bash>
176# Back up first!
177cp /path/to/dokuwiki/data/meta/calendar/2027-03.json /tmp/backup-2027-03.json
178
179# Delete corrupted file
180rm /path/to/dokuwiki/data/meta/calendar/2027-03.json
181
182# Recreate the recurring event in the calendar UI
183</code>
184
185=== Option 2: Manual Fix ===
186
187<code bash>
188# Edit the file
189nano /path/to/dokuwiki/data/meta/calendar/2027-03.json
190
191# Ensure it's valid JSON - use a validator like:
192# https://jsonlint.com/
193
194# Save and test
195</code>
196
197=== Option 3: Reset Empty File ===
198
199If the file exists but is corrupted, reset it to empty:
200
201<code bash>
202echo '{}' > /path/to/dokuwiki/data/meta/calendar/2027-03.json
203</code>
204
205Then recreate events through the UI.
206
207==== Checking DokuWiki Error Logs ====
208
209The updated plugin now logs JSON errors to DokuWiki's error log:
210
211<code bash>
212# Check for JSON decode errors
213tail -f /path/to/dokuwiki/data/cache/error.log | grep Calendar
214
215# Or view recent errors
216tail -100 /path/to/dokuwiki/data/cache/error.log | grep Calendar
217</code>
218
219Look for messages like:
220  * ''Calendar: JSON decode error in /path/to/2027-03.json: Syntax error''
221  * ''Calendar: JSON decode error in /path/to/2027-03.json: Unexpected end of file''
222
223==== Full Diagnostic Checklist ====
224
225Run through this checklist:
226
227<HTML>
228<table>
229<tr><th>Step</th><th>Command</th><th>Expected Result</th></tr>
230<tr>
231  <td>1. Check file exists</td>
232  <td><code>ls -la /path/to/dokuwiki/data/meta/calendar/2027-03.json</code></td>
233  <td>File should exist with size > 0</td>
234</tr>
235<tr>
236  <td>2. View file contents</td>
237  <td><code>cat /path/to/dokuwiki/data/meta/calendar/2027-03.json</code></td>
238  <td>Valid JSON structure</td>
239</tr>
240<tr>
241  <td>3. Validate JSON</td>
242  <td><code>php debug_events.php "" 2027-03</code></td>
243  <td>"✓ Valid JSON"</td>
244</tr>
245<tr>
246  <td>4. Check event count</td>
247  <td>Output from debug script</td>
248  <td>Shows recurring events</td>
249</tr>
250<tr>
251  <td>5. Check error logs</td>
252  <td><code>tail /path/to/dokuwiki/data/cache/error.log</code></td>
253  <td>No Calendar errors</td>
254</tr>
255<tr>
256  <td>6. Browser console</td>
257  <td>F12 → Console tab</td>
258  <td>"Rebuilding calendar... with X date entries"</td>
259</tr>
260</table>
261</HTML>
262
263==== Common File Locations ====
264
265Depending on your DokuWiki installation:
266
267  * **Default:** ''/var/www/html/dokuwiki/data/meta/calendar/''
268  * **Debian/Ubuntu:** ''/usr/share/dokuwiki/data/meta/calendar/''
269  * **Custom:** Check your DokuWiki ''conf/local.php'' for ''savedir''
270
271To find your data directory:
272
273<code bash>
274# From DokuWiki root
275php -r "include 'inc/init.php'; echo DOKU_INC . 'data/meta/calendar/';"
276</code>
277
278==== Still Having Issues? ====
279
280If you've checked everything and events still don't appear:
281
282  - Share the output of: ''php debug_events.php "" 2027-03''
283  - Share the browser console output when navigating to the month
284  - Share the contents of the JSON file: ''cat 2027-03.json''
285  - Check file permissions: ''ls -la /path/to/dokuwiki/data/meta/calendar/''
286
287The web server needs read/write access to the calendar directory:
288
289<code bash>
290# Fix permissions (adjust www-data to your web server user)
291chown -R www-data:www-data /path/to/dokuwiki/data/meta/calendar/
292chmod -R 755 /path/to/dokuwiki/data/meta/calendar/
293</code>
294
295===== Quick Reference =====
296
297<code bash>
298# View March 2027 events
299php /path/to/dokuwiki/lib/plugins/calendar/debug_events.php "" 2027-03
300
301# View all calendar files
302ls -la /path/to/dokuwiki/data/meta/calendar/
303
304# Check for errors
305tail -f /path/to/dokuwiki/data/cache/error.log | grep Calendar
306
307# Validate JSON online
308cat 2027-03.json | curl -X POST -H "Content-Type: application/json" -d @- https://jsonlint.com/
309</code>
310
311----
312
313**Version:** 3.2\\
314**Last Updated:** January 24, 2026
315