Troubleshooting

APIEngine log

<install folder>\log\ibs.log, rotated by the Logging settings

<install folder>/log/ibs.log

Startup errors

Event Viewer, Windows Logs, Application, source IIS AspNetCore Module V2

journalctl -u apiengine (or the unit name chosen at install)

Startup exception detail

<install folder>\logs\stdout_*.log, only while stdoutLogEnabled="true" in web.config

journalctl -u apiengine

Installer log

install.log beside install.ps1

install.log beside install.sh

Version (no sign-in)

GET https://<hostname>/api/v1/diagnostic/version

{"result":"<version>"}

Ping (no sign-in)

GET https://<hostname>/api/v1/ping (v95 and earlier: /api/ping)

{"result":true}

Full diagnostic

Sign in with POST /api/v1/auth/basic, then GET /api/v1/diagnostic with the token in the Authorization: Bearer <token> or User-Token header

Every row reports "success": true

0

Success, self-check passed

None

1

Package incomplete: APIEngine.dll or the VERSION file is missing

Download and extract the package again

2

Unsupported host: 32-bit PowerShell or PowerShell older than 5.1

Run from 64-bit Windows PowerShell 5.1 or PowerShell 7

3

Not elevated (Windows) or not root (Linux)

Run as Administrator, or with sudo

10

Answer file missing or unreadable

Check the -AnswerFile or --answer-file path

11

Misuse: quick install on a server with no existing install, install folder overlapping the package folder, bad port, or a site name that matches nothing

Read the message; add -Unattended for a scripted first install, or extract the package somewhere else

12

Post-install verification failed: the running APIEngine does not report the package version

The previous install is kept as <install folder>.bak.<timestamp>; check for a process holding files and re-run

13

A prerequisite is missing: IIS, the ASP.NET Core Module (.NET 8 Hosting Bundle), the ASP.NET Core 8 runtime, Apache or an Apache module

Install what the message lists, then re-run. Nothing on the server is changed when the run stops with this code

14

Files under the install folder are still locked after the app pool stopped (Windows)

Close whatever holds the files and re-run

20

Self-check failed for another reason

Read the failed checks at the end of install.log

HTTP 500.19, error 0x8007000d

The ASP.NET Core Module is not registered, usually because IIS was added after the .NET 8 Hosting Bundle

Re-run the .NET 8 Hosting Bundle installer, then iisreset

HTTP 500.19 after the module is confirmed

web.config carries .NET Framework sections from a v95 install copied over the top

Install v96+ into an empty folder, or remove the <system.web>, <runtime> and <system.codedom> sections

HTTP 500.21

Application pool CLR version is wrong for the release

v96+: No Managed Code. v95 and earlier: v4.0

HTTP 500.30

APIEngine started and then failed

Set stdoutLogEnabled="true" in web.config, recycle the pool, repeat the request and read logs\stdout_*.log. Turn it off again afterwards

HTTP 500.31

The ASP.NET Core 8 runtime is missing

Install the .NET 8 Hosting Bundle

HTTP 404 on every /api/... route while static files load (v95 and earlier)

ASP.NET 4.x is not registered with IIS

Run aspnet_regiis -iru and confirm the pool is v4.0, Integrated

Browser cannot connect over HTTPS right after an install. The installer printed No https binding was created - there is no certificate to bind to one. or The HTTPS binding on this existing site has no certificate.

No certificate is bound to the site's HTTPS binding: none was chosen, or the existing site never had one

Bind a certificate from LocalMachine\My or LocalMachine\WebHosting to the HTTPS binding in IIS Manager, or run netsh http add sslcert with the thumbprint the installer printed. Until then, check the site from the server itself on http://127.0.0.1:8080 (/api/v1/ping, /api/v1/diagnostic/version); that port is not reachable from other computers. See Certificates

Linux: Apache answers with its own error page

The apiengine service is stopped, or the vhost still uses the placeholder certificate

Run systemctl status apiengine; point SSLCertificateFile and SSLCertificateKeyFile at the server's certificate and reload Apache. See Certificates

Diagnostic row DataSource Connection fails, or ping fails

Wrong server, port, database or login in the Data Server Connection settings

Correct them on the Settings page and use Test Connection before saving

Diagnostic request fails with a pool timeout

The data server is unreachable from the APIEngine server

Check the network path and firewall to the data server port

Diagnostic row App_Data Permissions or Log directory fails

The application pool identity lacks Modify on the folder

Run the icacls command shown in the row

"Access to the path ... is denied" in the log

Same as above, for a folder first used by a feature (file server, SMS media, and the report folders in v95 and earlier)

Grant Modify on that folder to IIS AppPool\<pool>

Slow first request after a quiet period

The application pool went idle

Set Start Mode to AlwaysRunning and Idle Time-out to 0

401 {"error":"Token expired."}

The token's lifetime has passed

Sign in again for a new token

401 {"error":"Not Authorized."}

No token, a token signed with a different Token Secret, or a managed token that is inactive or expired

Sign in again. After the Token Secret changes, every earlier token is refused

Log: "Error validating managed token. Please ensure APIEngine Settings are correct and stored procedure token_manage_validate is functioning properly."

The managed-token check against the database failed

Check the data server connection and that token_manage_validate exists in the SBN database

Settings page shows a not-authorized message, or an action returns "Must be run from local server."

The Settings page and its actions accept requests from the server itself only

Sign in to the APIEngine server and browse to https://localhost:<port>/

"Report services retrieval is not configured (disabled, or no instance has a URL)." (v96 and later)

The ReportServices block is off or has no instance URL. Saving the Settings page resets it

Set it in App_Data\apiengine.settings and recycle the pool; see Reports

"All report service instances failed:" (v96 and later)

No Report Service instance answered; the message gives the reason for each

Call GET /api/v1/diagnostic/reportservices and fix the instance it names; see Reports

"Report PDF path is not configured." or "Unable to access report directory" (v95 and earlier)

The Crystal Report Destination path is blank or unreadable

Set the path in the Reporting section of the Settings page and use its Test button

Installation search returns 503

Search is disabled, or no endpoint has a URL

Enable it and add an endpoint on the Settings page; see SBN-Search

"No configured sbn-search endpoint is reachable and ready to search."

No endpoint answered

Use Test Connection in the Search section; check the SBN-Search service and the endpoint token