User errors¶

Most user-facing errors come down to invalid configuration in the creation of the YAML files. To verify a configuration, check that all files have correct input, with no typos, correct values, and a correct file structure. The errors below are categorized by the component that raises them: the gateways, the Process Manager, or the processes themselves (TP, IDB, and so on).

Config exceptions¶

Error names	Description	Suggested actions
InvalidFileForConfigLoadException	The config file name passed to the CSV loader was empty or not a symbol.	Check the logs for the file being loaded; the name must be a valid (non-null) symbol.
InvalidRegexForConfigFindException	A config-file lookup was made with an empty search pattern.	Usually internal — check the logs for the failing lookup and raise with support if it persists.
MultipleConfigurationFileMatchException	The config-file search pattern matched more than one file, so Refinery can't choose one.	Make the file name/pattern unique in the config folder.
NoConfigurationException	Refinery searched the pipeline and default config folders but found no file matching the expected name.	Check the logs for the file name it looked for and confirm it exists in your pipeline or default config folder.
ProcessInformationNotSetException	A config lookup ran before the process knew which pipeline it belongs to.	Ensure the process started and registered with the Process Manager; check the startup logs.

Connection exceptions¶

Raised by the shared connection library when a configured host/port is invalid. These can surface from any component that opens a connection (Process Manager, merge, reference data, and so on).

Error names	Description	Suggested actions
InvalidHostnameTypeException	A configured hostname wasn't a string.	Provide the hostname as a string in the host/port configuration.
InvalidPortException	A configured port wasn't greater than zero.	Correct the port value.
InvalidPortTypeException	A configured port wasn't a whole number.	Correct the port to be a whole number.

Dashboard exceptions¶

Error names	Description	Suggested actions
InvalidDashboardTargetException	The target process name for a dashboard query was empty or not a symbol.	Point the dashboard at a valid process name; for more information see accessing Refinery via dashboards.

Entrypoint exceptions¶

Error names	Description	Suggested actions
EntrypointConfigurationFailureException	The entrypoint can't initialise because the system data hierarchy is empty, or the pipeline configuration for this process is empty.	Add data-hierarchy values to the system YAML, and check the pipeline YAML processes are configured correctly.
InvalidLegacyRoutesConfigurationException	The legacy-routes file is empty, missing a required column, or has a route with no data-hierarchy values.	Disable legacy routing, or fix the legacy-routes file under state-config; see entrypoint pipeline config.
InvalidPipelineConfigurationException	A requested pipeline configuration value doesn't exist in the loaded system pipelines.	Verify the pipeline YAML is set up correctly.
InvalidPipelineNameException	The pipeline name was empty/not a symbol, or names a pipeline that isn't in the system.	Check the pipeline name at the top of the pipeline YAML.
InvalidTableNameException	The table name was empty/not a symbol, or names a table with no loaded schema.	Validate the table name in the schema YAML.
MultipleMatchingSchemasException	More than one schema matches the requested taxonomy and table name, so Refinery can't choose one.	Make the taxonomy + table name unique in the schema YAML.
NoMatchingSchemaException	No loaded schema matches the requested taxonomy and table name (or no schemas are loaded).	Check the taxonomy and table name in the schema YAML.

Gateway exceptions¶

Error names	Description	Suggested actions
GwDownstreamProcessErrorException	The gateway failed to register with a downstream process.	Check the failing process's logs for the underlying error.
GwDownstreamProcessInvalidResponseException	A downstream process returned a registration response missing the status or dataAvail field.	Check logs for more information.
GwInvalidArgumentTypeException	A gateway query argument had the wrong type.	Check the argument types for the function; see gateway.
GwInvalidDownstreamProcessException	A process the gateway has no record of tried to register with it.	Make sure that the whole system has been restarted since any pipeline config changes.
GwInvalidPreProcessingException	A gateway query's pre-processing step failed.	Check the query arguments and gateway logs; see gateway.
GwInvalidProcessDataUpdateException	A downstream process sent a data-availability update that was empty or referenced unknown fields.	Check the logs of the process that sent the update.
GwInvalidRouteException	The gateway couldn't build a valid route for the query's data hierarchy.	Check the data-hierarchy values target a live pipeline; see gateway.
GwNoArgumentsException	A gateway query was sent with no arguments.	Provide the required argument dictionary for the function; see gateway.
GwNoRouteException	No pipeline matches the query's data hierarchy, so the gateway has nowhere to route it.	Confirm a pipeline serves that data type/hierarchy and is running; see data sharding.
GwPostProcessingFailedException	A gateway post-processing handler failed while building the query result.	Check logs for more information.
InvalidArgumentsForGatewayException	The gateway query was sent with empty or non-dictionary arguments.	Pass a non-empty argument dictionary; see gateway.
InvalidDataHierarchyException	One or more data-hierarchy values in the query were null.	Provide non-null values for the data-hierarchy parameters.
InvalidDateArgumentsException	The query's end date is earlier than its start date.	Set the end date on or after the start date.
InvalidFunctionForGatewayException	The function name in a gateway query was empty or not a symbol.	Provide a valid function symbol; see gateway.
InvalidGatewayRegistrationException	A gateway tried to register with an empty name or empty config.	Check logs and pipeline status with pipeline CLI commands.
InvalidGwClientModeException	The client mode wasn't one of local, sync, async or qr.	Use one of the supported client modes.
InvalidGwExecuteTypesException	A gateway execute request had wrong types: queryId must be a GUID, function a symbol, arguments a dictionary.	Correct the parameter types.
InvalidGwFunctionException	The function in a gateway query was empty or not a symbol.	Ensure the correct gateway query structure; check gateway logs if it persists.
InvalidPipelineException	The named pipeline has no available instances.	Look into how to create pipelines.
InvalidPipelineStatusException	A pipeline-status notification to the gateway used a non-boolean "failed" flag.	Internal signal — validate pipeline health from the logs.
InvalidPrimarySourceException	There's no current primary instance for the pipeline to switch from.	Start/restart the pipeline using the refinery pipeline CLI command.
InvalidPrimaryTargetException	The target pipeline instance for the primary switch doesn't exist or has no available processes.	Confirm the target instance is up using the refinery failover CLI command and the refinery pipeline CLI command.
InvalidProcessException	The named process has no available instances.	Check out the process layout for more information.
InvalidProcessStatusException	A process-status notification to the gateway used a non-boolean "failed" flag.	Internal signal — validate process health from the logs.
InvalidTargetGatewayException	The target gateway name was empty or not a symbol.	Provide a valid gateway process name; see gateway.
NoDataHierarchyException	The query specified none of the data-hierarchy parameters.	Include at least one data-hierarchy element in the query.
NoGatewaysAvailableException	There are no gateway processes to send the query to — none are registered, or all have failed.	Check pipelines are up and the Process Manager is running; restart the Process Manager with the refinery process manager CLI command if needed.
NoInstancesForFailoverException	Failover was requested but the pipeline/process has only one instance.	Check instance status with the refinery failover CLI command.
NoProcessNameForGwException	The gateway couldn't determine its own process name at start-up.	Configuration/state issue — check logs, confirm pipeline health, and use the refinery failover CLI command.
PrimaryTargetAlreadyFailedException	The pipeline instance you tried to make primary (or one of its processes) has already failed.	Check logs for the affected processes.
TargetInstanceProcessNotAvailableException	A target process for the primary switch couldn't be reached.	Start/restart the pipeline using the refinery pipeline CLI command.

Monitoring exceptions¶

Error names	Description	Suggested actions
InvalidDataTypeException	The monitoring data type didn't match an existing monitoring table.	Use `process` or `system` as a symbol; see monitoring for more.
InvalidIntervalException	The metric interval wasn't a timespan greater than zero (null is allowed for event-based metrics).	Set a positive timespan; see the different q data types.
InvalidMetricFunctionException	The named metric function doesn't exist.	Within the Monitoring Daemon, check the metric function name is defined.
ProcessAlreadyRegisteredException	The process is already registered with a monitoring daemon, so the duplicate registration was ignored.	Verify the process's registration; check logs.

Pipeline processes exceptions¶

These are grouped by process and ordered by the path data takes through a pipeline: a shared General group, then Tickerplant → real-time engine (RTE) → IPDB → PDB → HDB.

General (all data processes)¶

Errors that any data process can raise — for example when building its on-disk storage path or loading its tables.

Error names	Description	Suggested actions
InvalidDataPipelineInstanceException	The pipeline instance used to build a data storage path was missing or not a whole number.	Make the pipeline instance a whole number; see create pipelines.
InvalidDataPipelineNameException	The pipeline name used to build a data storage path was empty or not a symbol.	Use the pipeline name exactly as set in the system YAML example.
NoConfigurationException	The Process Manager returned no configuration for this process (for example, the Tickerplant or IPDB).	Verify the pipelines are set up correctly.
NoSchemasAvailableException	No schemas are available for this pipeline's data hierarchy, so the data processes (TP, RDB, LDIDB, PDB) can't build their tables.	Make the system YAML data hierarchy match the one used by your pipelines/schemas.

Tickerplant¶

Error names	Description	Suggested actions
InvalidHandleForSubscriptionException	The connection handle to the Tickerplant wasn't a positive integer.	Verify the target Tickerplant is running using the refinery service class CLI commands.
InvalidTablesForSubscriptionException	The list of tables to subscribe to was empty.	Verify the schema YAML is correct.
InvalidTickerPlantSubscriptionResponseException	The Tickerplant's subscription reply was missing schema or journal information.	Confirm the subscription went to the right Tickerplant and check its logs.
InvalidTpBatchSizeException	The Tickerplant batch size isn't a positive whole number.	Check logs for information on the batch limit.
InvalidTpPublishConfigurationException	The configured Tickerplant publish function doesn't exist.	Check logs and confirm the publish function name is valid.
InvalidTpRolloverConfigurationException	The configured Tickerplant rollover (end-of-day) function doesn't exist.	Check logs and confirm the rollover function name is valid.
InvalidTpRolloverTimeException	The Tickerplant rollover time isn't a non-negative timespan.	Set a rollover time of 0D or greater.
InvalidTpTimerFrequencyException	The Tickerplant timer frequency isn't a positive whole number.	Verify the TP config in the pipelines is set up correctly.
NoDeltaMessagingServerException	Delta Messaging is enabled but no messaging server is set in the system config.	Set a Delta Messaging server value in the system config.
TickerPlantJournalCorruptedException	The Tickerplant journal couldn't be replayed because it is corrupted.	Check the TP logs; the pipeline's journal file may need clearing/restoring before restart.
TickerPlantSubscriptionFailedException	The Tickerplant rejected the subscription request.	Check logs for the reason the subscription was refused.

Real-time engine (RTE)¶

Error names	Description	Suggested actions
NoUpdFunctionsException	The RTE (real-time engine) process has no update functions configured.	Configure at least one update function for the RTE in the pipeline.

IPDB¶

Error names	Description	Suggested actions
InvalidIpdbWriteRowFrequencyException	The IPDB write row frequency isn't a positive whole number.	Modify the IPDB row frequency to be a positive whole number.
InvalidIpdbWriteTimerFrequencyException	The IPDB write timer frequency isn't a positive timespan.	Modify the IPDB timer frequency to be a positive timespan value.
MultipleIpdbsNotSupportedException	The pipeline has more than one IPDB; only one is supported.	Modify the pipeline YAML file to contain 1 instance of an IPDB.

PDB¶

Error names	Description	Suggested actions
PdbConfigurationException	PDB settings failed validation — for example, unknown tables, or incompatible partition/persist types.	Check the logs for the specific issue and verify your pipeline YAML.

HDB¶

Error names	Description	Suggested actions
HdbReloadFailedException	The HDB failed to reload, or building a missing partition failed.	Check the logs for the underlying error.

Process exceptions¶

Error names	Description	Suggested actions
InvalidPipelineConfigurationException	A pipeline config is missing its required `name` or `type` key.	Look into how to create pipelines.
InvalidPipelineInstanceToGetException	A process lookup used a pipeline instance that wasn't a whole number.	Make sure the pipeline instance is a whole number; check logs.
InvalidPipelineToGetException	A process lookup used a pipeline name that wasn't a symbol.	Make sure the pipeline name is a symbol; check logs.
InvalidProcessTypeToGetException	A process lookup used a process type that wasn't a symbol.	Specify the process type as a symbol.
InvalidSystemConfigurationException	The system config is missing the data-hierarchy key, or it's empty.	Look into how to create pipelines.
NoHostPortForProcessException	A target process is registered but has no host/port, so it isn't actually reachable.	Ensure that `ALL` pipelines defined in YAML are running. Also verify the target process is running using the refinery pipeline CLI commands. Reboot pipelines once the Gateway is up if the error is still occurring.
NoMatchingProcessesForConnectException	No process matches the pipeline, instance and type requested for connection.	Verify the health of all pipelines. Check that all processes are running using the refinery pipeline CLI commands.
ProcessConnectionFailedException	A connection attempt to a process failed or timed out.	Verify the target process is running using the refinery pipeline CLI commands.
ProcessDataHierarchyNotSetException	Code tried to add processes before the system data hierarchy was set.	Modify the system YAML to contain a data hierarchy; see how to create system pipelines.
ProcessIdNotSetException	Code tried to add processes before this process's own ID was set.	Verify that the pipelines are set up correctly.

Process Manager exceptions¶

Error names	Description	Suggested actions
DuplicatePipelineNameException	A pipeline with this name has already been loaded.	Modify the pipeline name to be unique (see pipeline example).
DuplicateProcessException	More than one configuration exists for the same process name.	Remove the duplicate process from your Process Manager config.
ExistingTaxonomyException	The taxonomy is already in use by another pipeline.	Make the taxonomy unique across pipelines (see pipeline and schema YAMLs).
ExtraTaxonomyValueException	A taxonomy contains a key that isn't part of the system data hierarchy.	Only use data-hierarchy keys in the taxonomy.
InvalidColumnTypeException	A column uses a data type Refinery doesn't support.	Check the logs for the column; valid data types can be found in the logs.
InvalidEndPersistTypeException	A pipeline mixes incompatible end-persist-types (date/month/year partition can't co-exist).	Use a single compatible end-persist-type across the pipeline's tables.
InvalidPipelineException	A process registered claiming a pipeline that doesn't match its configuration.	Verify that the pipelines are set up correctly.
InvalidPipelineInstanceException	One or more requested pipeline instances don't exist for the pipeline.	Modify the pipeline to contain the missing instance(s) (see create pipelines).
InvalidPipelineYamlFileException	The pipeline YAML file name was empty or not a symbol.	Verify that the pipelines are set up correctly.
InvalidPortException	A process registered on a different port than its configuration expects.	Check logs for the expected and actual ports.
InvalidProcessException	A registration arrived from a process not present in the Process Manager config.	Check the processes defined in the Process Manager config.
InvalidProcessManagerTargetException	One or more Process Manager targets aren't valid host/port values.	Verify the process is running using the refinery service class CLI commands, then boot/reboot the Process Manager using the PM CLI commands.
InvalidRealtimePipelineConfigurationException	A realtime pipeline has no schemas linked to it via taxonomy, so it won't start.	All realtime pipelines must have at least one schema associated with them via matching taxonomy.
InvalidRealtimePipelineException	A realtime pipeline is missing its IPDB or EPDB.	Both IPDB and EPDB must exist for persistence.
InvalidSchemaConfigException	One or more columns in the schema are missing the required `name` field.	Verify that the schema YAML is correct — every column needs a `name`.
InvalidSchemaYamlFileException	The schema YAML file name was empty or not a symbol.	Validate that the schema YAML is correct.
InvalidSystemYamlFileException	The system YAML file name was empty or not a symbol.	Verify that the system YAML is set up correctly.
InvalidTaxonomyTypeException	A taxonomy isn't a dictionary mapping data-hierarchy keys to values.	Verify that the taxonomy in the pipeline and schema YAMLs is set up correctly.
InvalidTimezoneException	A pipeline's configured timezone isn't a supported timezone.	Use a supported time zone.
JournalReplayWithIDBException	`journal-replay-on-restart` is true for a pipeline that has both an RDB and an IDB, which isn't allowed.	Modify the `journal-replay-on-restart` setting to be false. To restart the RDB after failure occurs, execute the `refinery pipeline` CLI command `refinery pipeline --recover-rdb`.
MissingTaxonomyValueException	A taxonomy omits a hierarchy element out of order (you can only drop the lowest elements).	Provide the missing taxonomy value(s) in the pipeline and schema YAMLs.
MultiplePipelineException	An operation that works on one pipeline at a time received more than one.	Internal — check logs; usually indicates a malformed request, raise with support if it persists.
NoActiveProcessManagersException	No running Process Managers were found.	Verify the process is running using the refinery service class CLI commands, then boot/reboot the Process Manager using the PM CLI commands.
NoProcessManagerConnectionException	There's no active Process Manager connection when trying to register or signal ready.	Verify the process is running using the refinery service class CLI commands, then boot/reboot the Process Manager using the PM CLI commands.
NoProcessManagerConnectionInfoException	No Process Manager host/ports are configured to connect to.	Verify the process is running using the refinery service class CLI commands, then boot/reboot the Process Manager using the PM CLI commands.
NoSystemConfigurationException	No system configuration is available — either no system-config folder/file exists on disk, or it hasn't been loaded yet — so the Process Manager can't proceed.	Make sure a valid config folder exists (see create pipelines); confirm the Process Manager is running using the refinery service class CLI commands and reboot it with the PM CLI commands if needed.
NullPipelineTypeException	A process tried to subscribe to the Process Manager before its pipeline type was set.	Verify that your pipelines are set up correctly (see create pipelines).
PipelineInstanceAlreadyRunningException	A start was requested for an instance that already has running processes.	Stop the pipeline, or force-start the offline processes.
PipelineInstancesNotRunningException	A stop was requested but no processes from those instances are running.	Restart the application using the refinery application CLI commands.
ProcessManagerConnectionFailedException	The process couldn't connect to any configured Process Manager.	Verify the process is running using the refinery service class CLI commands, then boot/reboot the Process Manager using the PM CLI commands.
ProcessManagerRegistrationException	The Process Manager rejected the registration or returned an invalid response.	Verify the process is running using the refinery service class CLI commands, then boot/reboot the Process Manager using the PM CLI commands.
ProcessOnIncorrectHostException	A process registered on a different host than its configuration expects.	Check logs for the expected and actual hosts.
ReservedPipelineNameException	The pipeline name matches a name reserved for non-Refinery-process pipelines.	Modify the pipeline name so it doesn't use a reserved name.
SubscriptionFromProcessManagerClientException	A subscription request came from a process that is itself a Process Manager client.	Restart the Process Manager using the PM CLI commands; if it persists, restart the application using the refinery application CLI commands.
SystemConfigurationAlreadyLoadedException	The system configuration has already been loaded and load was called again.	Restart the Process Manager to load a new system configuration using the PM CLI commands.
TaxonomyExistsForTableException	This taxonomy is already defined for the table.	Remove the duplicate taxonomy for the table in the pipeline and schema YAMLs; no duplicates allowed.
UnknownSettingException	The config contains a setting key that isn't defined in the JSON schema.	Verify that the schema YAML is correct and there are no typos.

Environment-based pipeline configuration¶

Validation errors specific to environment-based pipelines.

Error names	Description	Suggested actions
EnvironmentProcLayoutNotDefinedException	The pipeline's proc-layout has no entry for the current environment (or `all-environments`).	Add an `all-environments` and/or the named environment entry to proc-layout.
EnvironmentProcessesNotDefinedException	The pipeline's processes don't define the current environment (or `all-environments`).	Add `all-environments` and/or the named environment to the processes config.
EnvironmentVariableNotDefinedException	The environment variable named by the pipeline's `environment` setting isn't set.	Set the referenced environment variable before starting the pipeline.

Schema exceptions¶

Raised when building/registering a table definition in the schema library, after its YAML has parsed — that is, the file loaded but the table it describes is invalid. For file-level parse failures see YAML exceptions.

Error names	Description	Suggested actions
InvalidTableConfigurationException	The table's configuration block was empty or not a dictionary.	Check the table's settings in the schema YAML.
InvalidTableNameException	The table name was empty/not a symbol, or names a table that isn't registered.	Check the table name in the schema YAML.
InvalidTableSchemaException	The defined schema wasn't an empty table (it must declare columns/types only, with no rows).	Check the column definitions in the schema YAML.
TableAlreadyExistsException	A table with this name is already registered and overwrite is off.	Rename the table, or allow overwrite, in the schema YAML.
TableAlreadyExistsInRootNamespaceException	An object with the same name as the table already exists in the root namespace.	Rename the table in the schema YAML.

Sharding exceptions¶

Raised when sharded RDB/RTE data distribution is configured. See data sharding.

Error names	Description	Suggested actions
InvalidShardConfigurationException	A sharding parameter is invalid — for example, total-shards isn't a positive whole number, or the shard number is out of range.	Correct the sharding parameters; see data sharding.
InvalidShardTypeException	The configured shard type isn't one of the available shard functions.	Use a supported shard type (for example, md5 or first-letter); see data sharding.

UDF exceptions¶

Raised when running user-defined functions via getUDF. See UDF.

Error names	Description	Suggested actions
UdfDoesNotExistException	The requested user-defined function isn't registered in the system.	Check the UDF name, or register it; see UDF.
UserDefinedFunctionFailedException	A user-defined function ran but raised an error.	Check the log for the UDF's error message and fix the function logic.

YAML exceptions¶

Raised by the YAML parser when loading a config file — system, pipeline or schema YAML — before its contents are interpreted, that is, the file itself won't load. For errors in a table definition after the file parses, see Schema exceptions.

Error names	Description	Suggested actions
InvalidRootNodeException	The top-level node the parser was asked to read was empty or not a symbol.	Usually a malformed config file — check the file structure and the logs for which file/node failed.
InvalidYamlFileException	The config file path doesn't exist or isn't a file.	Confirm the config file exists at the configured path.
YamlParseFailedException	The parser couldn't read the requested node from the config file.	Check the config file's YAML syntax (the log line includes the parser's error). You can use this YAML validator to see where the issue lies.