nextcloud-nodered-ocs-api/docs/TROUBLESHOOTING.md

Troubleshooting

Nodes missing from palette

Symptom

Node-RED runs but Nextcloud nodes do not appear under Manage palette → Nodes.

Checks

1. Entrypoint ran

   docker logs nextcloud-node-red 2>&1 | head -20
   

   Expect:

   [entrypoint] Installing nextcloud nodes into /data...
   [entrypoint] Source: /opt/nextcloud-nodes/node-red-contrib-nextcloud-ocs
   [entrypoint] Target: /data/node_modules/node-red-contrib-nextcloud-ocs
   

   If you only see the Node-RED banner with no [entrypoint] lines, the image may still use CMD instead of ENTRYPOINT ["/entrypoint.sh"] — rebuild from current Dockerfile.

2. Module installed in userDir

   docker exec nextcloud-node-red ls /data/node_modules/node-red-contrib-nextcloud-ocs
   docker exec nextcloud-node-red cat /data/node_modules/node-red-contrib-nextcloud-ocs/package.json
   

3. User directory

   Logs must show User directory : /data. If it shows /usr/src/node-red/.node-red/, entrypoint did not start Node-RED with --userDir /data.

4. Stale volume (old package version)

   Compare /opt vs /data:

   docker exec nextcloud-node-red sh -c \
     'grep version /opt/nextcloud-nodes/node-red-contrib-nextcloud-ocs/package.json; \
      grep version /data/node_modules/node-red-contrib-nextcloud-ocs/package.json'
   

   If /opt is newer, restart should copy on boot. If /data stays old, remove volume (loses flows):

   docker rm -f nextcloud-node-red
   docker volume rm node-red-data
   docker run -d --name nextcloud-node-red --network host \
     -v node-red-data:/data --restart unless-stopped nextcloud-node-red:latest
   

5. Browser cache

   Hard refresh (Ctrl+F5) or open Node-RED in a private window.

---

Container restart loop

Symptom

docker ps shows Restarting; logs repeat entrypoint lines.

Cause

Old entrypoint.sh tried to copy missing settings.js:

cp: can't stat '/usr/src/node-red/.node-red/settings.js': No such file or directory

Fix

Use current entrypoint.sh (starts node-red --userDir /data only). Rebuild:

docker build --no-cache -t nextcloud-node-red:latest .

---

No Nextcloud configuration node selected

Flow nodes reference a deleted or unconfigured nextcloud-config node. Open each red Nextcloud node and re-select the config node, then Deploy.

---

API errors / connection refused

Issue	Fix
ECONNREFUSED to localhost	Use --network host or use LAN IP / hostname, not 127.0.0.1 from bridge network
SSL errors	Self-signed: nodes set rejectUnauthorized: false; or install proper certs
401 Unauthorized	Use app password, correct username
404 on OCS path	App not installed/enabled on Nextcloud (Collectives, Talk, etc.)

Test from container:

docker exec nextcloud-node-red wget -qO- --header="OCS-APIRequest: true" \
  --user='USER:APP_PASSWORD' \
  https://cloud.example.com/ocs/v2.php/cloud/user

---

Docker build shows old files

Build context must include updated nodes/nextcloud-ocs/:

grep version nodes/nextcloud-ocs/package.json   # on host before build
docker build --no-cache -t nextcloud-node-red:latest .

docker builder prune -af clears COPY layer cache.

---

Nextcloud iframe blank

1. Browser DevTools → Console: CSP violations.
2. Confirm nodered_embed is enabled and admin URL matches iframe target host.
3. CSPListener adds frame-src for the hostname from nodered_url.
4. Reverse proxy must not set X-Frame-Options: DENY on Node-RED.

curl -I https://cloud.example.com | grep -i frame
curl -I http://192.168.1.26:1880 | grep -i frame

---

Permission denied on entrypoint copy

Old files in volume owned by root. Fix:

docker rm -f nextcloud-node-red
docker volume rm node-red-data
# recreate container

Or fix ownership once:

docker exec -u root nextcloud-node-red chown -R node-red:node-red /data

---

Verify node discovery manually

docker exec nextcloud-node-red node -e "
  const p=require('/data/node_modules/node-red-contrib-nextcloud-ocs/package.json');
  console.log(p.version, Object.keys(p['node-red'].nodes).length, 'nodes');
"

Expected: version from package.json and 16 node types.