Troubleshooting¶
Resolve service startup, connection, document input, and restore problems.
The service is not active¶
Cause: cloud-init has not finished, or sushi-docling-api.service failed.
The demo does not validate your own documents.
Fix:
sudo cloud-init status --wait
sudo -iu ubuntu
sudo systemctl is-active sushi-docling-api.service
sudo systemctl show sushi-docling-api.service -p ActiveState -p SubState -p NRestarts
sudo journalctl -u sushi-docling-api.service --no-pager -n 50
Do not recreate the instance identity or start a second server to bypass a startup failure.
The workstation cannot call port 8443¶
Cause: the Session Manager forward is not running, or the client does not trust this instance's certificate.
Fix: forward port 8443 and keep the session open. Trust the server.crt
from this instance. Do not disable certificate verification. Use
sushi-docling-api on the instance when you do not want to copy the
credential file.
A document is rejected¶
Cause: the file is not PDF or DOCX, is over 10 MiB, or the PDF is over 20 pages. Scanned pages are outside this package.
Fix: use a PDF with selectable text inside those limits, one file at a time. Compare headings, numbers, and table cells with the source before you keep the Markdown. The request shape is in Convert your first document.
Data is missing after a restore¶
Cause: state and identity were not restored together.
Fix: restore /var/lib/docling, /etc/docling, and
/home/ubuntu/.config/sushi/docling from the same backup. A new Marketplace
version does not update a running instance. See
Operations.
Last updated November 1, 2026 · Suggest an improvement