1# Troubleshooting
2
3Common issues and solutions when using Gordon.
4
5## Registry Issues
6
7### "unauthorized: authentication required"
8
9**Cause:** Registry authentication is enabled but credentials are missing or invalid.
10
11**Solutions:**
12
131. Login to registry:
14   ```bash
15   docker login registry.mydomain.com
16   ```
17
182. Check token is valid:
19   ```bash
20   gordon auth token list
21   ```
22
233. Generate new token:
24   ```bash
25   gordon auth token generate --subject myuser --expiry 0
26   ```
27
28### "connection refused" on push
29
30**Cause:** Gordon is not running or registry port is blocked.
31
32**Solutions:**
33
341. Check Gordon is running:
35   ```bash
36   systemctl --user status gordon
37   # or
38   pgrep -f "gordon start"
39   ```
40
412. Check registry port is accessible:
42   ```bash
43   curl -v http://localhost:5000/v2/
44   ```
45
463. Check firewall:
47   ```bash
48   sudo firewall-cmd --list-ports
49   ```
50
51### "unknown: image not found"
52
53**Cause:** Image was pushed but no route configured.
54
55**Solution:** Add route to config:
56```toml
57[routes]
58"app.mydomain.com" = "myapp:latest"
59```
60
61Then reload:
62```bash
63gordon reload
64```
65
66## Deployment Issues
67
68### Container starts but app not accessible
69
70**Causes and solutions:**
71
721. **Wrong port exposed:**
73   Check your Dockerfile exposes the correct port:
74   ```dockerfile
75   EXPOSE 3000
76   ```
77
782. **Multiple ports - wrong one selected:**
79   Add `gordon.proxy.port` label:
80   ```dockerfile
81   LABEL gordon.proxy.port=3000
82   ```
83
843. **App not listening on 0.0.0.0:**
85   Ensure app binds to `0.0.0.0`, not `127.0.0.1`:
86   ```javascript
87   app.listen(3000, '0.0.0.0');
88   ```
89
90### Container keeps restarting
91
92**Cause:** Application crashing on startup.
93
94**Solutions:**
95
961. Check container logs:
97   ```bash
98   docker logs gordon-app-mydomain-com
99   ```
100
1012. Check Gordon logs:
102   ```bash
103   gordon logs -f
104   ```
105
1063. Run container manually to debug:
107   ```bash
108   docker run -it registry.mydomain.com/myapp:latest sh
109   ```
110
111### Environment variables not loaded
112
113**Cause:** Env file not found or wrong format.
114
115**Solutions:**
116
1171. Check file exists with correct name:
118   ```bash
119   ls ~/.gordon/env/
120   # Should show: app_mydomain_com.env (dots → underscores)
121   ```
122
1232. Check file permissions:
124   ```bash
125   chmod 600 ~/.gordon/env/app_mydomain_com.env
126   ```
127
1283. Check file format (no spaces around `=`):
129   ```bash
130   # Correct
131   KEY=value
132
133   # Wrong
134   KEY = value
135   ```
136
137### Secrets not resolved
138
139**Cause:** Secret provider not available or secret not found.
140
141**Solutions:**
142
1431. For `pass` backend:
144   ```bash
145   # Check pass is available
146   which pass
147
148   # Check secret exists
149   pass show myapp/db-password
150   ```
151
1522. For `sops` backend:
153   ```bash
154   # Check sops is available
155   which sops
156
157   # Check file can be decrypted
158   sops -d secrets.yaml
159   ```
160
161## Network Issues
162
163### Containers can't reach each other
164
165**Cause:** Network isolation enabled but services not in same network.
166
167**Solutions:**
168
1691. Check attachments are configured:
170   ```toml
171   [attachments]
172   "app.mydomain.com" = ["postgres:latest"]
173   ```
174
1752. Check containers are in same network:
176   ```bash
177   docker network inspect gordon-app-mydomain-com
178   ```
179
1803. Use correct hostname (image name before colon):
181   ```javascript
182   // Correct
183   connect("postgresql://postgres:5432/mydb")
184
185   // Wrong
186   connect("postgresql://localhost:5432/mydb")
187   ```
188
189### DNS resolution failing
190
191**Cause:** Container can't resolve service names.
192
193**Solutions:**
194
1951. Verify network isolation is enabled:
196   ```toml
197   [network_isolation]
198   enabled = true
199   ```
200
2012. Check both containers in same network:
202   ```bash
203   docker network inspect gordon-app-mydomain-com
204   ```
205
206## Volume Issues
207
208### Data not persisting
209
210**Cause:** Volume not configured or not preserved.
211
212**Solutions:**
213
2141. Add VOLUME to Dockerfile:
215   ```dockerfile
216   VOLUME ["/data"]
217   ```
218
2192. Check volume preservation:
220   ```toml
221   [volumes]
222   preserve = true  # default: true
223   ```
224
2253. List volumes:
226   ```bash
227   docker volume ls | grep gordon
228   ```
229
230### Disk full
231
232**Cause:** Registry or logs consuming too much space.
233
234**Solutions:**
235
2361. Check disk usage:
237   ```bash
238   du -sh ~/.gordon/*
239   ```
240
2412. Prune unused images:
242   ```bash
243   docker image prune -a
244   ```
245
2463. Configure log rotation:
247   ```toml
248   [logging.file]
249   max_size = 100
250   max_backups = 3
251   ```
252
253## Configuration Issues
254
255### Config not reloading
256
257**Cause:** Gordon not watching config file.
258
259**Solution:** Manual reload:
260```bash
261gordon reload
262```
263
264### "failed to read config file"
265
266**Cause:** TOML syntax error.
267
268**Solution:** Validate TOML:
269```bash
270# Check for syntax errors
271cat ~/.config/gordon/gordon.toml | tomlv
272# or use online validator
273```
274
275## Logging Issues
276
277### No logs appearing
278
279**Cause:** File logging not enabled.
280
281**Solution:** Enable in config:
282```toml
283[logging.file]
284enabled = true
285path = "~/.gordon/logs/gordon.log"
286```
287
288### Container logs missing
289
290**Cause:** Container log collection disabled.
291
292**Solution:**
293```toml
294[logging.container_logs]
295enabled = true  # default: true
296```
297
298## Diagnostic Commands
299
300```bash
301# Check Gordon status
302systemctl --user status gordon
303
304# View Gordon logs
305gordon logs -f
306journalctl --user -u gordon -f
307
308# List containers
309docker ps -f "label=gordon.managed=true"
310
311# List networks
312docker network ls | grep gordon
313
314# List volumes
315docker volume ls | grep gordon
316
317# Check container logs
318docker logs gordon-app-mydomain-com
319
320# Inspect container
321docker inspect gordon-app-mydomain-com
322
323# Check connectivity
324curl -v http://localhost:5000/v2/
325curl -v http://localhost:8080/
326```
327
328## Getting Help
329
330- [GitHub Issues](https://github.com/bnema/gordon/issues)
331- [GitHub Discussions](https://github.com/bnema/gordon/discussions)
332
333## Related
334
335- [Installation](../installation.md)
336- [Configuration](../config/index.md)
337- [CLI Commands](../cli/commands.md)