Skip to main content
We recommend accessing the server through the UAExpert tool to verify endpoints and inspect node structures.
This assumes that you have first run the configuration tool as described in the configuration settings.

​
Connection and certificate issues

If the extractor is unable to connect to the OPC UA server or maintain a secure session, try these solutions.
Do not leave source.auto-accept: true or source.ignore-certificate-issues: true enabled in production. These flags disable certificate validation and expose telemetry and credentials to interception. Use them only for short diagnostic tests while you set up certificate trust. See Configure SSL certificates and proxy settings for extractors.
If you get the error message Unable to connect to discovery server, make sure that you have specified the correct endpoint-url in the configuration file and that it’s possible to connect to the server from where the extractor is running.Solution:
  1. Confirm endpoint-url in the configuration file.
  2. From the extractor host, connect with UAExpert to verify network reachability.
Cause: The username or password in the configuration file or environment variables does not match what the OPC UA server expects.Solution: Verify the credentials in the configuration file or environment variables, then restart the extractor.
Cause: The OPC UA server does not trust the extractor’s client certificate. OPC UA uses mutual server/client certificate validation, so the connection is rejected.Solution:
  1. Move the extractor’s client certificate into the OPC UA server’s trusted certificate store.
  2. For a short connectivity test during initial setup, you can temporarily set source.auto-accept: true in the configuration file, then set it back to false. See the warning in Connection and certificate issues.
For comprehensive certificate and proxy guidance across runtime environments, see Configure SSL certificates and proxy settings for extractors.
This typically occurs if the server can’t handle a high load. Try to inspect what the extractor was doing as it crashed, then reduce source/browse-nodes-chunk, source/browse-chunk, source/attributes-chunk, or source/subscription-chunk in the configuration file.Solution:
  1. Reduce chunk sizes in config.yml: reduce source/browse-nodes-chunk, source/browse-chunk, source/attributes-chunk, or source/subscription-chunk.
  2. Increase source/keep-alive-interval.
Cause: The server certificate is signed with SHA1. The extractor treats SHA1 certificates as insecure and rejects them by default.Solution:
  • Update the server certificate to use SHA-256.
  • As a temporary diagnostic workaround only, set <RejectSHA1SignedCertificates>false</RejectSHA1SignedCertificates> under SecurityConfiguration in opc.ua.extractor.Config.xml, or set source.ignore-certificate-issues: true in config.yml. See the warning in Connection and certificate issues.
Cause: The server certificate key length is below the required security minimum.Solution:
  • Increase the key length of the server certificate.
  • Alternatively, adjust MinimumCertificateKeySize under SecurityConfiguration in opc.ua.extractor.Config.xml, or set source.ignore-certificate-issues: true as a temporary diagnostic workaround only. See the warning in Connection and certificate issues.
Cause: The server certificate lacks the data-encipherment usage flag required by the OPC UA standard.Solution: Reissue the server certificate with standard data encipherment key usage flags, or set source.ignore-certificate-issues: true as a temporary diagnostic workaround only. See the warning in Connection and certificate issues.
Cause: The secure channel was terminated because of a server-side session timeout, network interruption, certificate expiration, or server restart.Solution:
  1. Check the OPC UA server logs for session disconnect reasons.
  2. Increase session-timeout and keep-alive-interval in the extractor configuration file.

​
Browse and hierarchy issues

If the extractor encounters errors when traversing the server hierarchy or discovering nodes, try these solutions.
Cause: Server-side resource constraints or concurrency limits fail when the extractor browses a large node tree.Solution: Reduce the browse load on the server:
  • Set browse-chunk: 100 and browse-nodes-chunk: 100 in the configuration.
  • Set max-parallelism: 1 and max-node-parallelism: 1 to serialize queries.
Cause: The OPC UA server’s response exceeds message encoding limits because the namespace is large or a single response returns too many child nodes.Solution:
  1. Reduce browse-chunk and browse-nodes-chunk in config.yml (for example, down to 5 or 10).
  2. If using the .NET extractor, increase message buffer limits in opc.ua.extractor.Config.xml:
    • MaxStringLength
    • MaxMessageSize
    • MaxByteStringLength
    • MaxArrayLength
Cause: The server invalidated browse continuation points after a nightly restart, a maintenance window, or a short session continuation timeout.Solution:
  1. Reduce browse-nodes-chunk and browse-chunk to complete browse operations faster within single sessions.
  2. Set max-parallelism: 1.
  3. Set ignore-continuation-points: true in the configuration to re-initiate browse queries when continuation points become invalid.

​
Bad or missing data

If the extractor is unable to retrieve data, skips variables, or receives data in the wrong format from the OPC UA server, try these solutions.
Cause: The server has no mappable variables, string or non-scalar types are filtered out, or root-node and filter settings omit the nodes.Solution:
  1. In UAExpert, confirm that variables appear as green labels.
  2. Try setting extraction.data-types.allow-string-variables to true.
  3. If time series are still missing, check their dimensions. By default, the extractor requires variables to be scalar or fixed-size 1D arrays. Try setting extraction.data-types.unknown-as-scalar to true if variables have ValueRank equal to Any or OneOrMoreDimensions.
  4. Verify that the variables are not excluded by filters or omitted root node configurations.
Cause: The extractor infers data types from server definitions, and some variables are missing type metadata.If you write to a data modeling project and the variable is an OPC UA enumeration or multi-state type, enable extraction.data-types.states.enabled to ingest both the numeric code and string label into a state time series. See Extracting state time series with the OPC UA extractor.Solution:
  1. Set extraction.data-types.auto-identify-types to true.
  2. Set extraction.data-types.null-as-numeric to true to treat variables with null DataType as numeric (only do this if you are certain none of these should be strings). If this is the case, either verify that the variables are not excluded by filters or omitted root node configurations, or contact the server administrator. Unknown data types aren’t supported by the extractor, except with this workaround.
Cause: The extractor maps OPC UA variables to time series and properties to metadata. The server represents some metadata as variables.Solution: Use extraction.transformations in the configuration file to explicitly select and remap specific variable nodes to metadata.
Cause: The extractor requires scalar values or fixed-size arrays by default, so it skips variables with undefined array dimensions.Solution: Set extraction.data-types.unknown-as-scalar: true to treat dynamic or unspecified arrays as scalar values. You can also disable estimate-array-sizes to reduce startup evaluation overhead.
Cause: Historical backfill queries stale NodeIDs. This can happen if the raw node buffer skips node re-discovery after structural changes on the source server.Solution:
  1. Disable raw-node-buffer in the configuration file to force fresh node discovery.
  2. Clean up stale historical state in the CDF staging area if needed.

​
State time series

If the extractor does not create state time series, fails to push state sets, omits string labels, or does not pick up state definition changes, try these solutions.
Cause: State time series ingestion is disabled, the extractor is not set up through Integrations, the extractor is not writing to a data modeling project, the service principal lacks write access, or the OPC UA variable is not a supported type.Solution:
  1. Verify that extraction.data-types.states.enabled is set to true in the configuration file.
  2. Confirm that the extractor writes to a data modeling project.
  3. Confirm that the service principal has datamodelinstances:write for the target space.
  4. Confirm that the OPC UA variable matches a supported variable type. The extractor chooses multi-state, enumeration, or two-state discrete handling automatically during browse; there is no separate configuration for that choice.
  5. Confirm that the extractor is set up through Integrations (public preview).
  6. For enumeration variables, set extraction.data-types.auto-identify-types to true.
  7. Restart the extractor as described in Start the extractor so it rebrowses the node tree.
  8. If multi-state variables are still missing after restart, set extraction.data-types.states.allow-non-standard-types to true. See the states configuration reference.
Cause: The extractor could not write CogniteStateSet instances to CDF.Solution: Search extractor logs for Failed to push state sets in CDF. See OPC UA extractor metrics for log configuration.
Cause: The variable already has a numeric or string time series in CDF, often from earlier ingestion with enums-as-strings. Enabling extraction.data-types.states.enabled does not convert or delete that series. The extractor does not delete time series or data points.Solution:
  1. Search extractor logs for skipping creation of state timeseries. The existing time series is unchanged.
  2. If you previously ingested the variable as a string time series and want state time series instead, delete the existing time series and reingest after you enable state time series ingestion. This avoids duplicate series for the same variable. Whether you migrate is optional.
Cause: The OPC UA variable defines more than 100 states at browse, which exceeds the CDF platform limit for state sets.Solution: The extractor ingests the variable as a regular time series and does not create a CogniteStateSet or state time series. Search extractor logs for more than the 100 a CDF state set allows. See OPC UA extractor metrics for log configuration.
Cause: The OPC UA variable initially had 100 or fewer states, but the state set in CDF later grew past the 100-state platform limit.Solution: The extractor logs an error and stops updating the time series. Search extractor logs for has accumulated and more than the 100 a CDF state set allows. Reconcile the state definitions on the OPC UA server or plan ingestion without a state time series for that variable. See OPC UA extractor metrics for log configuration.
Cause: The extractor received a state code or label that is not in the CDF state set. It writes a data point with status BadOutOfRange and no value.Solution:
  1. Search extractor logs for Writing a bad state data point with no value, is not one of the, and states its state set defines. See OPC UA extractor metrics for log configuration.
  2. Verify that OPC UA state definitions on the server match the state set in CDF.
  3. If the definitions changed recently, restart the extractor or set auto-rebrowse-period to refresh state sets.
Cause: The extractor does not detect live changes to state definitions on the OPC UA server. Updated state sets appear in CDF only after a rebrowse. Until then, state codes outside the old state set are written with status BadOutOfRange and have no value.Solution: Restart the extractor as described in Start the extractor to trigger a rebrowse. Alternatively, set auto-rebrowse-period in the configuration file.
Cause: FiniteStateMachineType is not a supported OPC UA state variable type.Solution: Ingest multi-state variables (one state list per tag) or enumeration variables (one shared state list per type) instead. See Supported OPC UA state variables.
Last modified on September 9, 2026