Troubleshooting

Symptom: 403 responses on routes that should work.

Likely cause: the host or port used in the URL does not match the address configured for the service (for example, access by IP or by an alternative name).

Solution: use exactly the host provided by the environment administrator in the base URL.

Symptom: 403 on /upload, /download/list, or /report, with a token accepted on other routes.

Likely cause: a user or environment rule blocks the operation: service disabled, user locked, time not allowed, file size, type, or name limit, or concurrent session limit.

Solution: check the access rules with the service administrator.

Symptom: /auth/login responds 206 Partial Content and does not create the session cookie.

Likely cause: the user has MFA enabled.

Solution: complete the second factor through the linkURL received, as described in Complete MFA.

Symptom: the /auth/login response has no field with the token.

Likely cause: local login delivers the session only in the __Host-dirl_session cookie.

Solution: store and resend the cookie (curl -c and -b) or get a Bearer token through the password grant.

Symptom: /auth/token or /oauth2/token responds 400 with error and error_description.

Likely cause: body sent as JSON instead of a form, missing required field, invalid grant_type or subject_token_type, source JWT not accepted, or provider not specified in token exchange.

Solution: send application/x-www-form-urlencoded with the fields in OAuth tokens and read error_description.

Symptom: calls that used to work start responding 401.

Likely cause: the token or the session expired, or the session was ended.

Solution: get a new credential and retry the call. See Expiration.

Symptom: GET /report responds with an error.

Likely cause: the required filterdirection parameter was not sent or has a value other than 5 (completed downloads) or 7 (completed uploads).

Solution: include filterdirection. See Query reports.

Symptom: a linkURL or a link received by email or SMS returns an error.

Likely cause: the link expired, was changed (for example, truncated when copied or with the query string re-encoded), or the file is no longer available.

Solution: use the full URL, unedited. If it has expired, generate a new link (new listing, new login, or new password request).

Symptom: the saved file is too small or contains text instead of the expected content.

Likely cause: the error response was saved as if it were the file, or the binary content was handled as text or JSON.

Solution: check the HTTP status before saving (curl --fail) and save the response as binary.

Symptom: manual calls to /sso/oauth2/cb or /sso/saml2/acs are rejected.

Likely cause: state, code, and SAMLResponse are issued and signed by the provider and bound to the browser session.

Solution: test SSO through the browser, starting at /sso/login?provider=<name>. See Single Sign-On.

Symptom: /auth/login, /auth/firstaccess or /auth/forget fails before the credentials are checked.

Probable cause: the environment requires Cloudflare Turnstile. 400: CF-Turnstile-Response header missing or invalid; 403: token rejected (invalid, expired or already used); 503: the API could not validate the token with Cloudflare.

Solution: generate a new widget token for each attempt and send it in the CF-Turnstile-Response header. On 503, try again. Integrations without a browser should use the password grant. See Cloudflare Turnstile.