> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/service-management-and-troubleshooting.md).
# Service management and troubleshooting
Operating the JD Edwards agent, and resolving common faults
### Service management
You can use the following commands to operate and maintain the agent:
| Action | Linux | Windows |
| ------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- |
| Status | `systemctl status balkanid-jde-agent` | `Get-Service BalkanIDJDEAgent` |
| Start / stop | `systemctl start\|stop balkanid-jde-agent` | `Start-Service\|Stop-Service BalkanIDJDEAgent` |
| Restart | `systemctl restart balkanid-jde-agent` | `Restart-Service BalkanIDJDEAgent` |
| Logs (follow) | `journalctl -u balkanid-jde-agent -f` | `Get-Content ...\logs\.log -Tail 50 -Wait` |
| Event log | Not applicable | `Get-EventLog -LogName Application -Source BalkanIDJDEAgent -Newest 10` |
| Reconfigure | `balkanid-jde-agent --configure` | same |
| Test the connection | `balkanid-jde-agent --test-connection` | same |
| Extract locally (uploads nothing) | `balkanid-jde-agent --dry-run --output ./out` | same |
| Run now (writes CSVs only; does not upload) | `balkanid-jde-agent --tui` → "Run extraction now" | same |
| Version | `balkanid-jde-agent --version` | same |
The agent reads `config.yaml` when it starts. Restart the service after any configuration change. The first extraction cycle runs immediately on start.
File locations are listed under [Installation](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#installation).
***
### Troubleshooting
Configuration keys are written as dotted paths. `jde.instances[]` means the key sits on one instance inside the `jde.instances` list. Every key, its default and its position are in the [configuration reference](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#configuration-reference).
| Symptom | Likely cause | Fix |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read config file` / `parse config file` at start-up | Config missing, unreadable by the service account, or invalid YAML | Re-run `--configure`; on Linux confirm `config.yaml` is owned by `balkanid`. |
| `tenant credentials not configured` / `no JD Edwards instances configured` | The service started against an incomplete configuration file | Run `--configure`, then restart. |
| Windows: service stops immediately, Event Log shows a logon failure | Service account lacks **Log on as a service** on this host | `secpol.msc` → Local Policies → User Rights Assignment → Log on as a service. |
| Windows **error 1069** | This host cannot retrieve the gMSA password, or the credential is wrong | Run `Test-ADServiceAccount`, reboot the host, re-run `install.ps1`. |
| Start-up rejects `auth_mode: windows` | Windows authentication is not supported on Linux | Set `jde.instances[].auth_mode: sql` with `jde.instances[].db_username` and `db_password`, or move the agent to a Windows host. |
| `dial tcp :1433: i/o timeout` | Nothing listening, or a firewall in between | `Test-NetConnection jde-sql -Port 1433` / `nc -vz jde-sql 1433`. |
| `Unable to open tcp connection with host 'jde-sql:0'` | Named instance entered as a bare host, or UDP 1434 blocked | Write the instance into `jde.instances[].host` (`jde-sql\JDEPROD`) and leave `jde.instances[].port` unset. |
| Oracle `ORA-12514` / `ORA-12505` | `service_name` and `sid` are different things | Set exactly one of `jde.instances[].service_name` or `jde.instances[].sid`, from `lsnrctl services` output. |
| x509 / TLS / certificate error on connect | `jde.instances[].encrypt` defaults to `true` and the server presents a self-signed cert | Install the issuing CA on the agent host, or set `jde.instances[].trust_server_certificate: true` on that instance. |
| Uploads or update checks fail on a certificate error | TLS-inspecting proxy on the outbound path | Add the proxy's issuing CA to the agent host's trust store. |
| `Login failed for user 'BALKANID_JDE_RO'` | Wrong `jde.instances[].db_password` | Stop the service, re-run `--configure` and retype the password, then start the service. |
| `Login failed for user 'NT AUTHORITY\ANONYMOUS LOGON'` or `DOMAIN\HOST$` | Service is running as `LocalSystem` under `jde.instances[].auth_mode: windows` | Re-run `install.ps1` with `-GmsaAccount` or `-ServiceCredential`. |
| `Login failed` naming the correct service account | Grants applied to a different principal | Re-run `grant-mssql.sql` with `AuditLogin` and `AuditUser` set to that account. |
| `The account is locked out` / Oracle `ORA-28000` | Each cycle spends another failed attempt | Stop the service, unlock the account, run `--configure`, then start the service. |
| Oracle `ORA-28001` | Password expired under the `DEFAULT` profile | Rotate the password, then re-run `--configure`. |
| `Invalid object name 'F0092'` | Wrong database, not a missing grant | Set `jde.instances[].system_database`, `object_database`, `data_database` and `control_database`. |
| Owners reported as `not discovered` | The login cannot enumerate the catalog (`VIEW ANY DATABASE` revoked) | Name all four `jde.instances[].*_database` keys explicitly. |
| Connects, but every count is zero | Wrong schema owner | Leave `jde.instances[].system_owner`, `control_owner`, `data_owner` and `object_owner` blank, and read the `owner discovery:` log lines. |
| `--test-connection` reports a required table `NOT READABLE` | No `SELECT` on `F0092`, `F95921`, `F00950` or `F0093` | Run the `GRANT` statement printed in the error. |
| An optional table is not readable | No `SELECT` on `F00926`, `F0094`, `F00941`, `F00942`, `F9860`, `F0101` or `F01151` | `GRANT SELECT` on the table named in the log; [insights](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup.md#insights-and-segregation-of-duties) that use it stay suppressed. |
| `F98OWSEC` permission denied | Not granted by the grant scripts | Use the view pattern in the grant script appendix. |
| `F00950 security records` = `0` | Missing grant, or an instance with no Security Workbench records | Confirm the grant; an empty Security Workbench permits every user every object. |
| `refusing to emit an empty extraction` / `extraction produced 0 entities` | A required read failed | Fix the grants in this order: `F0092`, `F95921`, `F00950`, `F0093`. |
| `heartbeat mode is disabled, skipping this cycle` | `server.heartbeat_mode` is `false` | Set `server.heartbeat_mode: true` and restart. |
| `extraction_interval` is set and ignored | Not a Go duration string (`2 hours`, `120`, `2 h` do not parse) | Write `server.extraction_interval` as `2h`, `24h`, `90m` or `30s`. Values under `30s` are raised to `30s`. `server.requests_interval` parses the same way. |
| Upload returns `401` or `403` | Bad `auth.tenant_key` or `auth.tenant_secret` | Re-copy both from the BalkanID platform. |
| `jd_edwards integration not found for tenant` | Integration not installed, or wrong `appId` | Install the `jd_edwards` integration, or set `auth.integration_id`. See [Which integration receives the data](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#which-integration-receives-the-data). |
| A snapshot lands in the wrong JD Edwards integration | `auth.integration_id` is blank and the tenant has more than one | Set `auth.integration_id` to the integration that should receive the data. See [Which integration receives the data](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#which-integration-receives-the-data). |
| [Insights](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup.md#insights-and-segregation-of-duties) name your CNC team as the largest risk | `security.cnc_principals` is empty | List the CNC user ids and role names in `security.cnc_principals`. |
| Environments are classified wrong | Names do not begin with `PD` or `PROD` | Add the prefix to `security.production_environment_prefixes`. |
| Warning at every start that `config.yaml` is readable by more than its owner | Inherited `%ProgramData%` ACL grants `BUILTIN\Users` read | Run the [directory hardening block](/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/installation-and-configuration.md#hardening-windows). |
***
### Uninstalling
The uninstallers ship in the release bundle. Both keep the configuration, extraction output and logs unless you pass the purge flag.
```sh
sudo ./uninstall.sh # service and binary
sudo ./uninstall.sh --purge # also removes config, state and logs
```
```powershell
.\uninstall.ps1 # service and install directory
.\uninstall.ps1 -Purge # also removes C:\ProgramData\BalkanID\jde-agent
```
`--purge` removes `/var/log/balkanid`, which is shared by every BalkanID agent on the host.
Ask your DBA to drop the read-only account once the agent is removed:
```sql
DROP USER [BALKANID_JDE_RO]; -- SQL Server, per database the agent read
DROP LOGIN [BALKANID_JDE_RO];
DROP USER BALKANID_JDE_RO CASCADE; -- Oracle
```
***
### Contacting support
Include the following:
* The output of `balkanid-jde-agent --version`, and the platform.
* The output of `balkanid-jde-agent --test-connection`.
* The relevant log lines, including the `owner discovery:` lines and the read counts. Database passwords, tenant secrets and AIS passwords are redacted from log lines and error messages.
* For extraction-shape questions, the output of `probe-schema.sql`. It is read-only and returns no user data, no Address Book data and no password material.
* For write-back questions, the output of `balkanid-jde-agent --check-ais`.
Do not attach `config.yaml`. It holds your database credential and your BalkanID tenant secret in cleartext. If a configuration value is relevant, quote the single key.
For additional support, please contact your BalkanID support representative.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/jd-edwards-integration-setup/service-management-and-troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.