system-readiness

Pre-flight check — validates config, credentials, database connectivity, and identity files before starting the agent.

Overview

When to use it

Run system-readiness before starting the agent for the first time, after changing credentials, or whenever you need to diagnose a connectivity or configuration issue. It exits immediately after the checks — it does not start the poll loop.

🚀

Before first start

Confirm everything is wired up before consuming the bootstrap token.

🔑

After changing credentials

Verify new credential references resolve and database connectivity works.

🔍

Diagnosing failures

Pinpoint exactly which check is failing without starting the full agent.

Reference

Each check explained

config

Loads and parses the configuration file. Validates all required fields are present, rejects unknown keys, and type-checks all values.

Pass: Configuration loads without errors and all required fields are valid.

Fail: Configuration file not found, required field missing, unknown key, or type mismatch.

db-readerreader user

Resolves the credential reference for the reader database user and opens a connection. The reader user is used by Discovery, Profile, and Certifier tasks.

Pass: Database login succeeds and a test query executes.

Fail: Secret cannot be resolved, credentials are invalid, or the database rejects the connection.

db-pipelinepipeline user

Same as db-reader but for the pipeline database user. The pipeline user is used by Operate tasks to execute certified DML.

Pass: Database login succeeds and a test query executes.

Fail: Secret cannot be resolved, credentials are invalid, or the database rejects the connection.

db-ddl_adminddl_admin user

Same as db-reader but for the DDL admin database user. Used by DDL Deploy tasks in development environments.

Pass: Database login succeeds and a test query executes.

Fail: Secret cannot be resolved, credentials are invalid, or the database rejects the connection.

identity

Verifies the identity directory exists and that the required bootstrap files are present (for first-run registration). If the agent is already registered, bootstrap files are not required.

Pass: Directory exists and is readable. Bootstrap files present if unregistered.

Fail: Directory does not exist, is not readable, or bootstrap files are missing on a fresh agent.

trust-ca

Verifies that the trust certificate exists and is a valid PEM-encoded certificate chain. This file is used to authenticate the platform on all secure connections.

Pass: File exists, is readable, and parses as a valid PEM certificate.

Fail: File missing, not readable, or not a valid PEM.

keypair

Checks that the agent's client keypair exists in the identity directory. On a brand new agent the keypair is generated during bootstrap — this check passes after bootstrap. On restart of a registered agent, the keypair should already be present.

Pass: Client private key and certificate are present and readable.

Fail: Keypair missing — agent may not have bootstrapped yet, or identity was reset.

Output

Reading the output

All checks passing

✅  config          Configuration loaded and validated
✅  db-reader       Reader user connected
✅  db-pipeline     Pipeline user connected
✅  db-ddl_admin    DDL admin user connected
✅  identity        Identity directory present, bootstrap files found
✅  trust-ca        Trust certificate readable
✅  keypair         Client keypair present

All checks passed — agent is ready to start.

A check failing

✅  config          Configuration loaded and validated
❌  db-reader       Reader user: invalid private key
✅  db-pipeline     Pipeline user connected
✅  db-ddl_admin    DDL admin user connected
✅  identity        Identity directory present, bootstrap files found
✅  trust-ca        Trust certificate readable
✅  keypair         Client keypair present

1 check failed. Fix the issues above and re-run.

The command exits with code 0 on full success and non-zero if any check fails. Use this in CI scripts or pre-start hooks to gate agent startup on a successful readiness check.

Troubleshooting

Common failures and fixes

❌ config

Required field missing in configuration

•Open your configuration file and ensure all required fields are set.

•Check for typos — unknown keys are rejected by the validator.

•Pass the config file path explicitly when running system-readiness.

❌ db-reader / db-pipeline / db-ddl_admin

Credential resolution failed

•Verify the secret manager reference matches the actual secret name in your secret manager.

•Ensure the agent host has the necessary permissions to access your secret manager.

•For file-based credentials (non-production), ensure the file exists, is valid JSON, and contains all required fields.

❌ db-reader / db-pipeline / db-ddl_admin

Invalid private key

•Ensure the private key in the credential is a valid PKCS8 RSA private key.

•Check that the matching public key is configured on the database user.

•Regenerate the keypair if needed and update both the database user and the secret manager.

❌ identity

Identity directory does not exist

•Run the directory setup script to create all required subdirectories.

•Verify the identity path in your configuration matches the actual directory.

❌ identity

Bootstrap files not found

•Download a new bootstrap package from the Console (Agents page) and extract it into the identity directory.

•The bootstrap token is time-limited — if it has expired, download a fresh package.

❌ trust-ca

Trust certificate not found

•The trust certificate is included in the bootstrap package. Re-extract the package into the identity directory.

•Verify the file is in the correct subdirectory for the environment.

Need help?

Email us at support@boltpipeline.ai