Skip to main content
Behavior change in FlowX.AI 5.9.1. Insert operations no longer accept a custom _id field._id is reserved and assigned internally by MongoDB. Supplying your own _id on insert was never supported and could cause errors on later reads, so Insert and Insert Many now reject any payload that contains an _id field with 400 Bad Request and the message _id is a reserved keyword. Remove _id from insert payloads; if you need to keep a custom identifier, store it under a different key (for example, externalId). Update and query operations are not affected.

​
Configuration

The service comes with most of the needed configuration properties filled in, but there are several environment variables that need to be set up for your specific deployment.

​
Database configuration

The NoSQL DB Runner connects to MongoDB for data persistence. Configure the following variables:
The MongoDB URI supports replica set configuration for high availability. The connection string includes multiple MongoDB instances and an arbiter for proper replica set functionality.

​
Configuring authorization & access roles

The NoSQL DB Runner validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the mainIdentity client registration) in the service-accounts realm:
Upgrading from 5.1.x? Remove the legacy opaque-token env vars: SECURITY_OAUTH2_REALM, SECURITY_OAUTH2_CLIENT_CLIENTID, SECURITY_OAUTH2_CLIENT_CLIENTSECRET, and SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the authentication and IAM migration guide for the full list.

​
FlowX operations document limit

This setting allows you to configure the maximum number of documents that can be retrieved from MongoDB in a single request.

​
External MongoDB connection caching

If you connect to many distinct external MongoDB instances, increase FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES to avoid frequent reconnections. Lower the TTL if your MongoDB credentials rotate frequently.

​
Relational database connection pooling

These defaults apply to all relational database data sources: Oracle, PostgreSQL, and IBM Db2.
Increase FLOWX_SQL_DEFAULTS_ROW_LIMIT if your workflows need to read more than 1000 rows in a single query. Adjust FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS for long-running analytical queries.

​
Database host restrictions

Available starting with FlowX.AI 5.9.5
Relational data sources (Oracle, PostgreSQL, and IBM Db2) and Unmanaged MongoDB data sources may only connect to hosts that resolve to a public address. If any address the hostname resolves to is private, the connection is rejected with 400 Bad Request, error key error.sql.internalHostNotPermitted, and the message Connection to internal addresses is not permitted: <host>. For MongoDB, the NoSQL DB Runner checks the hosts in the connection URI before connecting, then every address the driver resolves later, including replica-set members and mongodb+srv targets. A private address found at that later stage shows up as a connection timeout, not as the 400 error. The platform’s own MongoDB, which backs FlowX Database, is never checked.
Prefer a hostname entry over a CIDR block. A hostname covers every address that name resolves to, so it keeps working if the DNS record later gains another address. A CIDR block is matched per address, so every private address the hostname returns must fall inside an allowed block, or the connection is still rejected.
Loopback, link-local, and wildcard addresses are never permitted, even when the host is listed in FLOWX_SSRF_ALLOWED_HOSTS.

​
Configuring logging

Control log levels for different components of the service:
Using DEBUG log levels in production environments may impact performance and generate large log volumes. Consider using INFO or WARN levels for production deployments.

​
Configuring application management

Configure management endpoints and monitoring capabilities:

​
Prometheus metrics configuration

Enable Prometheus metrics export for monitoring:
The older form MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED also works (both resolve to the same setting). The property path above is the preferred form.

​
Troubleshooting

​
Common issues

Symptoms: Service fails to start with database connection errors.Solutions:
  1. Verify MongoDB connection string format and credentials
  2. Ensure MongoDB replica set is properly configured and accessible
  3. Check network connectivity between service and MongoDB instances
  4. Verify MongoDB user permissions and database access rights
Symptoms: Service cannot consume or produce Kafka messages.Solutions:
  1. Verify SPRING_KAFKA_BOOTSTRAP_SERVERS points to the correct broker(s)
  2. Check Kafka security protocol and authentication configuration
  3. Ensure network policies allow traffic to the Kafka cluster
  4. Verify topic names and consumer group assignments are correct
Symptoms: 401/403 errors when communicating with other FlowX services.Solutions:
  1. Verify OAuth client ID and client secret are correct
  2. Check OAuth server URL and realm configuration
  3. Ensure OAuth provider is accessible from the service
  4. Validate token endpoint URI configuration
Symptoms: An Insert or Insert Many operation returns 400 Bad Request with the message _id is a reserved keyword.Cause: _id is reserved and assigned by MongoDB. Supplying it on insert was never supported and could break later reads, so starting with FlowX.AI 5.9.1 it is rejected.Solution: Remove the _id field from the insert payload. If you need to keep a specific identifier, store it under a different key (for example, externalId).
Symptoms: An Oracle, PostgreSQL, IBM Db2, or Unmanaged MongoDB data source returns 400 Bad Request with the message Connection to internal addresses is not permitted: <host> (error key error.sql.internalHostNotPermitted).Cause: The hostname resolves to at least one private address. Every address a hostname resolves to is checked, so a host with several DNS records is rejected if any one of them is private, even when the others are public.Solution: If the database is legitimately on a private network, for example reached over a site-to-site VPN, add its hostname to FLOWX_SSRF_ALLOWED_HOSTS. See Database host restrictions.
Symptoms: An UPDATE, UPDATE_MANY, DELETE, or DELETE_MANY operation on a FlowX Database or Unmanaged MongoDB data source returns 400 Bad Request with the message <operation> requires a non-empty filter (error key error.collection.filterRequired).Cause: These operations are rejected when the filter is missing or empty, so a forgotten filter can’t change or delete every document in a collection.Solution: Add a filter to the operation. To match every document on purpose, use the filter {"_id": {"$exists": true}}.

Redis Configuration

Complete Redis setup including Sentinel and Cluster modes

Kafka Authentication

Configure Kafka security and authentication

IAM Configuration

Identity and access management setup
Last modified on October 30, 2026