Choose the symptom below. Run Docker commands from the folder containing `docker-compose.yaml`; the examples use the service name `app`. Replace the example hostname and port with your deployment values.

## Container fails to start

On the container host, run:

```bash
docker compose config --quiet
docker compose ps
docker compose logs --tail 200 app
```

Resolve the first startup error in the logs. Check the Docker image name, license key, Redis connection (if collaborative editing is enabled), and certificate and dictionary files. The mounted files must exist and be readable by the application.

After fixing the settings or files, run `docker compose up -d` and check the service status again.

## Port already in use

List the ports used by running containers:

```bash
docker ps --format "table {{.Names}}\t{{.Ports}}"
```

Check whether port `443` is already in use by another service on the host.

**Windows PowerShell:**

```powershell
Get-NetTCPConnection -LocalPort 443 -State Listen
```

**Linux:**

```bash
sudo ss -ltnp | grep ':443'
```

**macOS:**

```bash
sudo lsof -nP -iTCP:443 -sTCP:LISTEN
```

Identify the process listening on the port. NGINX or IIS provides the public HTTPS endpoint in the documented deployment. Ensure that only the intended service listens on the configured HTTPS address and port.

Also verify that the container's published application port does not conflict with another service.

## WOPI discovery endpoint returns an error

From the SharePoint server, run:

```powershell
curl.exe -i https://bolddocserver.example.com/hosting/discovery
```

- **Cannot connect:** Check DNS resolution, firewall rules, whether NGINX or IIS is listening on port `443`, and whether the application is running.
- **Certificate error:** Follow [HTTPS certificate errors](#https-certificate-errors).
- **404 or 500 through a proxy:** Follow [NGINX or IIS URL Rewrite returns 404 or 500](#nginx-or-iis-url-rewrite-returns-404-or-500).
- **XML contains the wrong hostname:** Set `WOPI_HOST_URL` to the public HTTPS address and apply the change with `docker compose up -d`.

## SharePoint cannot open a document

1. Check discovery from the SharePoint server using the command above.
2. In SharePoint Management Shell, run `Get-SPWOPIBinding` and `Get-SPWOPIZone`.
3. Check that bindings exist for the document type and that the selected zone is available in discovery.
4. Check that the user has permission and that their browser can reach BoldDocServer.

If a file opens in a desktop application instead of the browser editor, review the library’s document-opening settings and WOPI bindings with your SharePoint administrator.

For proof-signature errors in SharePoint logs, see [Proof-signature errors](../integrations/sharepoint-integration/#proof-signature-errors). For registration steps, see [Connect SharePoint](../integrations/sharepoint-integration).

## DOCX editing or saving fails

1. Open a simple Word document with an account that has edit permission.
2. Add one sentence, save, and wait for the save operation to complete.
3. Close and reopen the file from SharePoint.

If the sentence is missing or a save error appears, compare the application and SharePoint logs for that time. Check the save response and the user’s edit permission. Keep the editor open while resolving a reported save failure.

## XLSX editing or saving fails

Repeat the [saving checks](#docx-editing-or-saving-fails) with a simple workbook and a change to one cell. If only one workbook fails, collect its size, the operation, and reproduction steps for support.

## PDF viewing, annotations, or collaboration fail

Check PDF loading first, then try an annotation or form-field change. Save and reopen the PDF from SharePoint to check that the change remains. For multi-user issues, follow [Collaborative editing does not work](#collaborative-editing-does-not-work).

## Auto-save does not persist

Check `AUTO_SAVE_INTERVAL`, wait for the interval and the save operation to complete, then reopen the file from SharePoint. If the change is missing, follow the document-saving checks above.

If the content is saved but Version History has no new entry, check the SharePoint library’s versioning settings.

## Collaborative editing does not work

1. Set `ENABLE_COLLABORATIVE_EDITING` to `"true"` and apply changes with `docker compose up -d`.
2. Check `REDIS_CACHE_CONNECTION_STRING` and access from BoldDocServer to Redis.
3. Open the same file in separate browser sessions using two accounts with edit permission.
4. Make a change and check whether it appears in the other session.

Check the application and Redis logs for connection errors. Also verify that the required collaboration services are configured and running.

For IIS deployments, ensure the **WebSocket Protocol** feature is installed and enabled. For NGINX deployments, check that the configuration forwards WebSocket upgrade headers.

## Comments or Track Changes are missing

Check the document format and the available commands in its editor. Add a comment or tracked change to a simple Word document, save, and reopen it. If it disappears after saving, follow the [DOCX saving checks](#docx-editing-or-saving-fails).

## Access denied or permission errors

Check the user’s permission in the SharePoint library and whether the error occurs when opening or saving. An account may have view permission without edit permission. Compare the same operation with an authorized test account and review the corresponding SharePoint logs.

## HTTPS certificate errors

Check that the TLS certificate is valid for the public hostname and trusted by the system making the request. 

For NGINX deployments, verify the certificate and private key paths in the NGINX server block.

For IIS deployments, verify the HTTPS binding and selected certificate in IIS Manager.

If NGINX or IIS connects to BoldDocServer over HTTPS, also check the application endpoint's certificate and ensure that the HTTPS connection trusts it and that it is valid for the hostname used for the connection.

Correct certificate or trust problems rather than bypassing certificate validation.

## NGINX or IIS URL Rewrite returns 404 or 500

Verify that the BoldDocServer application is running and that the HTTPS endpoint forwards requests to the correct application address, protocol, and port.

**For NGINX deployments:**

- Check that the `proxy_pass` address, protocol, and port match the application endpoint.
- Verify that the NGINX configuration preserves the request path and query string.
- Check that WebSocket upgrade headers are configured.
- Validate the configuration using `nginx -t` and review the NGINX access and error logs.
- Verify that NGINX can reach the application endpoint.

**For IIS URL Rewrite deployments:**

- Verify that the URL Rewrite rule uses the correct application address, protocol, and port.
- Check that the rule preserves the request path and query string.
- Confirm that Application Request Routing (ARR) is installed and Proxy is enabled.
- Verify that IIS can reach the application endpoint.
- Review the IIS and application logs for the failed request.

If the application endpoint uses HTTPS, verify that its certificate is trusted and valid for the hostname used by the HTTPS endpoint.

## Resource or performance issues

On the container host, run:

```bash
docker stats
docker compose logs --since 30m app
```

Record CPU and memory usage, document size, and the number of users editing at the same time. Compare a simple document with the affected document to narrow down the issue before changing host resources.

## Collect logs for support

Include:

- The BoldDocServer Docker image name, host OS, and SharePoint version.
- Deployment details, including WSL 2, Docker, NGINX or IIS HTTPS configuration, and the URL Rewrite configuration where applicable.
- The failure time and time zone, error message, and HTTP status if available.
- The document format, size, and steps to reproduce the issue.
- Application, SharePoint, and NGINX or IIS logs covering the failure, as applicable.

Remove passwords, license keys, access tokens, private keys, and confidential document content before sharing files or screenshots.