Error Reference

Summary

This document describes how Velox creates, records, displays, and returns errors. It is an internal PKB reference for developers, AI agents, and technical writers. The source code is the authority; where the code only exposes a runtime exception or operating system error instead of a fixed message, this document states that explicitly.

The current source has several error surfaces:

• Flow/transport/module logs created through TvxLog.Error, TvxLog.Cancelled, TvxLog.Warning, TvxLog.Issue, and TvxLog.MessageLog.
• Designer dialogs created through MessageError.
• Windows Event Log entries created through gEventLogger.LogMessage(..., EVENTLOG_ERROR_TYPE, ...).
• REST/API HTTP responses created by TvxRESTManager, TRESTModule, and TvxLog.GetLogAPIResponse.
• Raised exceptions such as Exception.Create, Exception.CreateFmt, EOAuth2Exception.Create, and RaiseLastOSError.

Source scan scope for this document: Classes, Forms, VeloxService, and VeloxAPIService, excluding Vendor. The scan found hundreds of active error-producing expressions across explicit Velox log errors, user dialogs, service event-log errors, HTTP error responses, and raised exceptions. Repeated protocol/file/service patterns are grouped as message families with source locations rather than duplicated line-by-line.

Related PKB Documents

• ARCHITECTURE.md
• FLOW_EXECUTION.md
• SERVICE_REFERENCE.md
• MODULE_LIBRARY.md
• DATA_FORMAT_REFERENCE.md
• TECHNICAL_DEBT.md
• Flow Configuration
• System Runtime Configuration
• Transport Configuration

Source Code Locations

Area	Source
Log status types and status names	Classes\Tools\vxTypes.pas:109
Main log API	Classes\vxModule.pas:554, Classes\vxModule.pas:2751, Classes\vxModule.pas:2797, Classes\vxModule.pas:2802, Classes\vxModule.pas:2807, Classes\vxModule.pas:2812, Classes\vxModule.pas:2817, Classes\vxModule.pas:2824
Log status severity behavior	Classes\vxModule.pas:3403
Log item exception capture	Classes\vxModule.pas:3798
Log item database persistence	Classes\vxModule.pas:3915
Log header persistence	Classes\vxModule.pas:3512, Classes\vxModule.pas:3630
REST problem JSON response	Classes\vxModule.pas:3078
Designer message dialogs	Classes\GUI\vxMessages.pas:17, Classes\GUI\vxMessages.pas:25, Classes\GUI\vxMessages.pas:63
Windows Event Log integration	Classes\Tools\vxEventLogger.pas:22, Classes\Tools\vxEventLogger.pas:107
Deadlock detection	Classes\Tools\vxCommon.pas:131
Flow error call sites	Classes\vxActionMan.pas
Data/file error call sites	Classes\vxDataDef.pas, Classes\vxDBDef.pas, Classes\vxFileDef.pas, Classes\vxFileCon.pas, Classes\vxSQLConnection.pas, Classes\dmSystemDB.pas
Transport error call sites	Classes\Transports\*.pas
Service manager error call sites	Classes\Service\*.pas
Service executable error call sites	VeloxService\classMain.pas, VeloxAPIService\classMain.pas
API HTTP error call sites	Classes\Service\vxManagerREST.pas, VeloxAPIService\vxWebModule.pas
Configuration connection error call sites	Classes\vxCon.pas, Classes\vxConPool.pas
Runtime utility exception call sites	Classes\Tools\*.pas

Error Creation Model

TvxLog.Error

TvxLog.Error(aDescription, E) calls TvxLog.MessageLog(aDescription, Ord(flsError), E).

Behavior verified in source:

• Creates a TvxLogItem.
• Sets the item Description to the supplied message.
• Sets Level to Ord(flsError), which is 6.
• Calls TvxLogItem.AddE(E) when an exception is supplied.
• AddE stores ExceptionText, ExceptionType, and ExceptionStackTrace.
• TvxLog.SetStatusType(flsError) sets the log status type to Error and sets FStatus := False.
• If the log has no UI listener, the app is foreground, and execution is on the main thread, level 0, 6, and 30 messages call MessageError.

TvxLog.MessageLog

MessageLog is the central log item factory.

Level	Status effect	Meaning in current code
0	flsError	Error/system error, used by gSystemLog and MessageError.
1	no status change	Info.
2	flsWarning	Warning.
3	flsIssue	Issue.
4	flsDuplicate	Duplicate.
5	flsCancelled	Cancelled.
6	flsError	Error, used by TvxLog.Error.
7	no status change	Test line.
8	no status change	Highlight/note.
10	flsWarning	Warning, commonly system/user message warning.
20	no status change	System info.
30	flsError	User issue/error.
40	flsWarning	User warning.
50	no status change	Info-style level; exact semantic use was not exhaustively traced.

Deadlock Special Case

Before creating a log item, MessageLog calls CheckForDeadlock(E) unless the level is 5 (cancelled). Deadlock detection returns true when:

• an exception is assigned,
• the exception is EDataError, EOleException, or TDBXError,
• and the exception message contains DEADLOCK case-insensitively.

When true, the original message becomes Deadlock: <message>, TvxLog.Deadlock is used, log status becomes Cancelled, and FIsDeadLocked := True.

MessageError

MessageError(aMessage, HelpID, E) is the Designer/user dialog error surface.

Behavior:

• In background mode or off the main thread, it writes gEventLogger.LogMessage(aMessage, EVENTLOG_ERROR_TYPE, E).
• In foreground main-thread mode, it displays DialogError('Error', ...).
• In foreground mode, it also writes gSystemLog.MessageLog(aMessage, 0, E) when gSystemLog is assigned.
• Exception details include exception class, inner exception class if assigned, message, and a truncated stack trace.

gEventLogger.LogMessage

gEventLogger.LogMessage(aDescription, EVENTLOG_ERROR_TYPE, E) writes to two places:

• gSystemLog.MessageLog(aDescription, 0, E) when gSystemLog is assigned.
• Windows Event Log through ReportEvent.

For event-log error entries, the event ID is sCount + 4, where sCount is 1 when only message text is written and 2 when stack trace text is also written.

The event source is created under SYSTEM\CurrentControlSet\Services\Eventlog\Application\<process name> and uses vxEventMessages.dll when registry access is available. If event source registration fails, the code attempts to log Unable to register "EventMessageFile".; when no event source handle can be registered, the Windows Event Log write is skipped.

Raised Exceptions

Raised exceptions are not always directly logged at the throw site. They become logged only if caught by a surrounding Log.Error, MessageError, or gEventLogger.LogMessage path.

Important raised-exception categories:

• Exception.Create / Exception.CreateFmt for module-not-found, utility, timer, tag, file, shell, and script-file errors.
• RaiseLastOSError for Win32/OS failures. Runtime text includes Windows GetLastError details and therefore cannot be fully determined from source alone.
• EOAuth2Exception.Create in OAuth code. These exceptions are caught by calling transport/email code when used there.

REST/API Error Responses

REST/API errors are returned in two ways:

• HTTP status and reason strings are set by TvxRESTManager and TRESTModule.
• When a REST Flow itself fails, TvxLog.GetLogAPIResponse writes application/problem+json containing only log items whose level is 0, 6, or 30.

GetLogAPIResponse uses:

• code = ExceptionType and detail = ExceptionText when exception text exists.
• code = "error" and detail = Description when no exception text exists.
• instance = FNum, the saved log number.

Default REST Flow result codes in TvxActionMan.New are:

• Success: 200
• Client error: 400
• Server error: 500

These can be configured per REST Flow.

Error Codes And Status Values

Code/status source	Values
TvxLogStatusType ordinal values	flsNotSet=0, flsOK=1, flsWarning=2, flsIssue=3, flsDuplicate=4, flsCancelled=5, flsError=6, flsTest=7, flsHighlight=8
TvxLog.MessageLog error levels	0, 6, and 30 mark the log as Error.
Windows Event Log type	EVENTLOG_ERROR_TYPE is used for service/runtime errors.
REST Flow default HTTP codes	200, 400, 500; stored as Flow settings.
REST endpoint unavailable	503 when a TvxRESTItem is disabled.
REST fallback errors	500 for invalid FID, missing endpoint, REST timeout, default endpoint listing failure, and unexpected request execution errors.
Transport status	ftsSending, ftsCompleted, ftsCancelled, ftsFailed, ftsTest; persisted on VX_LOG_TRANSPORT.
IBM MQ codes	Completion and reason codes are decoded into messages through DecodeCompletionCode and DecodeReason; exact mapping was not traced in this document.
HTTP transport response codes	Uses server ResponseCode and ResponseText; exact values are remote-system supplied.
IPC client code	FIPCClient.LastError is shown in Designer IPC errors.
Windows/OS codes	RaiseLastOSError includes operating system error code/message at runtime; exact code is not statically knowable.

Persistence And Logging

Artifact	Table/code path	Notes
Log header	TvxLog.AddModule / TvxLog.SaveModule	Saves status, handled flag, start/end date, module name, log type, action/transport FIDs, folder, test flag, executor, and module type.
Log item	VX_LOG_ITEM via TvxLogItem.SaveToDB	Saves LOGNUM, LEVEL, STATUS, and truncated DESCRIPTION. SQL Server 2014 support path truncates to 448 chars; non-2014 path truncates to 840 chars. Exception text/type/stack are stored in the module blob, not in the simple VX_LOG_ITEM insert shown in SaveToDB.
File log	VX_LOG_FILE, VX_LOG_FILE_LINK	Created for read/write/download/audit/error/transport events.
Transport log	VX_LOG_TRANSPORT, VX_LOG_TRANSPORT_LINK	Stores transport status, attempts, next attempt date, save/send status filters, emails, and communication logging flags.
System log	gSystemLog	Receives MessageError and gEventLogger events when assigned.
Windows Event Log	ReportEvent	Used by services, background operations, and off-main-thread UI error calls.

User Guidance Model

The code embeds different user guidance styles:

• Configuration correction: "Please check your configuration", "Please update the transport configuration", "Please check the settings".
• External dependency correction: check database connection, remote transport server, mailbox, service account, file permissions, folder paths, certificates, OAuth credentials, XSD schema, or REST endpoint.
• Operational retry: restart VeloxService / VeloxAPIService, re-run the Flow, wait for locked files, or let outbound transport retry.
• Support escalation: messages that say "critical error", "program error", unknown field type, or "contact support" indicate a developer/support investigation rather than a normal user fix.

Where a message says "Processing cancelled ... (this is not an error)", the log status can be Cancelled even though the business condition is expected, commonly no source data or no test file found.

Subsystem Error Catalog

The catalog below groups the source-discovered explicit Velox error message families by subsystem. Dynamic message expressions are shown as source expressions because their final runtime text depends on the Flow, module, file, endpoint, exception, server, or operating-system state.

Flow Execution And Flow Steps

Important classes: TvxActionMan, TvxActionItem, TvxActionReport, TvxActionMap, TvxActionTransport, TvxActionSQL, TvxActionFileRouter, TvxActionSubAction, TvxActionCustomScript, TvxActionShellExecute, TvxActionPool, TvxExecutionMonitor.

Logging: Flow log through Log.Error/Log.Cancelled; some manual helper failures use MessageError; thread timeouts use gEventLogger.

Message or exception expression	Source	Cause	Recovery/user guidance
A Data Definition has not been assigned to this Report. Please check your configuration.	Classes\vxActionMan.pas:826	Report step missing source definition.	Edit Flow report step and assign the Data Definition.
Exception executing report action. Please check your configuration.	Classes\vxActionMan.pas:848	Report execution raised exception.	Review exception details, report source, output destination, and report configuration.
You must provide a file name for the report eg MyReport.pdf	Classes\vxActionMan.pas:984	Report file output has no filename.	Configure report output filename.
Error emailing report to <recipients>	Classes\vxActionMan.pas:1009	Report email send failed.	Check SMTP setup, recipients, credentials, attachment/output settings.
Report module has not been assigned. Please check your configuration.	Classes\vxActionMan.pas:1113	Report step has no report module.	Assign report module.
Error loading report module. Please check your settings.	Classes\vxActionMan.pas:1120	Referenced report could not load.	Check report FID/module exists and is not corrupt.
A source Data Definition has not been assigned to this Map. Please check your configuration.	Classes\vxActionMan.pas:1194	Map step missing source.	Assign source Data Definition.
A destination Data Definition has not been assigned to this Map. Please check your configuration.	Classes\vxActionMan.pas:1201	Map step missing destination.	Assign destination Data Definition.
Exception executing map action. Please check your configuration.	Classes\vxActionMan.pas:1233	Map execution raised exception.	Review map script, source/destination definitions, and exception detail.
Map module has not been assigned. Please check your configuration.	Classes\vxActionMan.pas:1265	Map step missing map module.	Assign map module.
Error loading map module. Please check your settings.	Classes\vxActionMan.pas:1272	Referenced map could not load.	Check map module exists and loads.
Unable to check transports as "File Connection to Monitor" is not assigned on the Execution tab. Please check your config.	Classes\vxActionMan.pas:1861	Manual transport check has no monitor file connection.	Configure Execution tab file connection.
Unable to check transports as there are no "Transports to Monitor" added on the Execution tab. Please check your config.	Classes\vxActionMan.pas:1864	Manual transport check has no inbound transport links.	Add transports to monitor.
Unknown error checking incoming transports	Classes\vxActionMan.pas:1893	Incoming transport check threw exception.	Review exception and transport configuration.
Transport check cancelled!	Classes\vxActionMan.pas:1907	Transport check ended cancelled.	Usually no data or cancellation; inspect log items.
Transport check failed with errors!	Classes\vxActionMan.pas:1908	Transport check status Error.	Inspect transport log items.
The "Reprocess until Error/Cancelled" loop valve has activated for [...]	Classes\vxActionMan.pas:1951	Reprocess loop exceeded local valve of 1000.	Review Flow source data and reprocess configuration. Code message says General Setup, but source shows local constant.
An unexpected critical error occurred while running flow [...]	Classes\vxActionMan.pas:1976	Unhandled exception escaped Flow execution.	Support/developer review; inspect exception stack.
*** There are no actions configured for this flow. The log will be flagged as cancelled. ***	Classes\vxActionMan.pas:2079	Flow has zero steps.	Add steps or accept as empty/no-op Flow.
<Execution/Sub-action> cancelled!	Classes\vxActionMan.pas:2187	Final Flow status Cancelled.	Usually no data, empty source, or explicit cancel; inspect prior log lines.
<Execution/Sub-action> failed with errors!	Classes\vxActionMan.pas:2188	Final Flow status Error.	Inspect preceding error item.
Program or configuration error while loading linked actions	Classes\vxActionMan.pas:2237	Linked Flow query/load failed.	Check linked Flow configuration and database.
The Flow passed to ExecuteFlow has not been assigned - critical error	Classes\vxActionMan.pas:2280	Child Flow instance missing.	Developer/support investigation.
The Flow passed to ExecuteFlow has not been loaded - critical error	Classes\vxActionMan.pas:2285	Child Flow failed to load.	Check child Flow exists and module can load.
Exception executing child action. Please check your configuration.	Classes\vxActionMan.pas:2310	Linked/sub Flow execution threw exception.	Inspect child Flow log and exception.
Unable to create flow from map	Classes\vxActionMan.pas:3186	Wizard/helper failed creating Flow from map.	Review selected map and save/load status.
Unable to create flow from report	Classes\vxActionMan.pas:3223	Wizard/helper failed creating Flow from report.	Review selected report and save/load status.
External command exit-code errors	Classes\vxActionMan.pas:3268, Classes\vxActionMan.pas:3282	Shell/process returned failure exit code.	Test command outside Velox, check command, parameters, credentials, service account, permissions.
Window station/desktop RaiseLastOSError errors	Classes\vxActionMan.pas:3311, Classes\vxActionMan.pas:3326, Classes\vxActionMan.pas:3329, Classes\vxActionMan.pas:3331	External command impersonation/UI desktop setup failed.	Check service account, interactive desktop permissions, and Windows error details.
Exception executing command line. Please test it using Start > Run	Classes\vxActionMan.pas:3357	Shell command raised exception.	Test command manually and review exception.
Error executing command line. Please test it using Start > Run	Classes\vxActionMan.pas:3364	Shell command execution returned failure without exception.	Test command manually.
An Outbound Transport has not been assigned to this Transport action. Please check your configuration.	Classes\vxActionMan.pas:3455	Transport step missing outbound transport.	Assign outbound transport.
A File Definition has not been assigned to this Transport action. Please check your configuration.	Classes\vxActionMan.pas:3462	Transport step missing source file definition.	Assign File Definition.
Exception executing outbound file transport. Please check your settings.	Classes\vxActionMan.pas:3542	Transport registration step threw exception.	Check outbound transport and file definition.
Transport module has not been assigned... / Error loading outbound transport module...	Classes\vxActionMan.pas:3566, Classes\vxActionMan.pas:3584, Classes\vxActionMan.pas:3591	Outbound transport link missing or module load failed.	Assign/re-save transport; confirm referenced module exists.
SQL Command is blank. Please check your configuration.	Classes\vxActionMan.pas:3626	SQL step has no SQL.	Configure SQL text.
A DB Definition has not been assigned to this SQL Command. Please check your configuration.	Classes\vxActionMan.pas:3634	SQL step missing DB Definition.	Assign DB Definition.
Error executing Custom SQL Action. Please check your SQL Statement	Classes\vxActionMan.pas:3655	SQL execution failed.	Review SQL text added to log item and exception.
A File Definition has not been assigned to this File Router action. Please check your configuration.	Classes\vxActionMan.pas:3722	File router step missing source.	Assign File Definition.
Error compiling script for route item "<name>"	Classes\vxActionMan.pas:3745	Route formula compile failed.	Correct route formula/script.
Error executing script for route item "<name>"	Classes\vxActionMan.pas:3756	Route formula execution failed.	Review formula and exception.
File router execution errors	Classes\vxActionMan.pas:3778, Classes\vxActionMan.pas:3782	File router failed.	Check source file definition, routes, destination file connections.
Exception executing sub action. Please check your configuration.	Classes\vxActionMan.pas:3870	Sub-action Flow execution failed.	Inspect child Flow.
A Flow has not been assigned to this Run Flow Command. Please check your configuration.	Classes\vxActionMan.pas:3902	Run Flow step missing target Flow.	Assign target Flow.
Error loading action module. Please check your settings.	Classes\vxActionMan.pas:3909	Target Flow cannot load.	Check target Flow exists and loads.
Custom script Data Definition/cancel/script errors	Classes\vxActionMan.pas:3972, Classes\vxActionMan.pas:3986, Classes\vxActionMan.pas:3999, Classes\vxActionMan.pas:4005, Classes\vxActionMan.pas:4012	Missing source, explicit user cancellation/failure, or script exception.	Assign source and review script/exception.
Max time-out reached waiting for flow threads to finish executing	Classes\vxExecutionMonitor.pas:206, Classes\vxExecutionMonitor.pas:215	Service shutdown/stop wait timed out.	Check stuck Flow threads and service shutdown logs.
Velox (...) has unassigned Action on thread ... (FreeActions)	Classes\vxActionPool.pas:294	Pooled action state corruption/unassigned action.	Developer/support investigation.

Data Definitions, Database Connections, And Files

Important classes: TvxDataDef, TvxDBDef, TvxFileDef, TvxFileCon, TvxSQLConnection, TvxSystemDB, TvxCon, TvxConPool.

Logging: Flow log for runtime data/file errors; Designer dialog for configuration JSON and setup errors; system log for connection pool failures.

Message or exception expression	Source	Cause	Recovery/user guidance
You have not specified any DB Connections for the '<name>' Data Definition	Classes\vxDataDef.pas:1273	DB Definition lacks DB connection links.	Add DB Connection(s).
Error connecting to database for '<name>' Data Definition	Classes\vxDataDef.pas:1292	Database connection open failed.	Check connection JSON, credentials, network, database availability.
A database connection could not be loaded	Classes\vxDataDef.pas:1303	Referenced connection module did not load.	Check DB connection references.
Please set the File Connection for the File Definition '<name>'	Classes\vxDataDef.pas:1326	File Definition missing File Connection.	Assign File Connection.
Error opening/closing '<name>' Data Definition	Classes\vxDataDef.pas:1428, Classes\vxDataDef.pas:1430	Data open/close exception.	Review data definition fields, DB/file source, exception.
SQL transaction errors	Classes\vxDataDef.pas:1563, Classes\vxDataDef.pas:1593, Classes\vxDataDef.pas:1625	Transaction start/commit/rollback failed.	Check database connection and transaction state.
Unable to save an in-active Data Definition	Classes\vxDataDef.pas:1837	Attempted save while inactive.	Activate/open definition before save path.
You have selected "Flag As Processed" but no dataviews are configured for flagging.	Classes\vxDBDef.pas:317	DB Definition flagging enabled without flag views.	Configure flag dataviews or disable flagging.
Unable to verify custom ID field... Unable to open database connection	Classes\vxDBDef.pas:366	Custom ID verification could not open DB.	Check DB connection.
JSON connection configuration errors	Classes\vxCon.pas:164, Classes\vxCon.pas:208, Classes\vxCon.pas:243, Classes\vxCon.pas:245, Classes\vxCon.pas:297, Classes\vxConPool.pas:328	Connections.json invalid, missing keys, duplicate DB keys, or incomplete connection definitions.	Correct Connections.json; ensure keys are unique and all DB roles are assigned.
System DB connection errors	Classes\dmSystemDB.pas:265, Classes\dmSystemDB.pas:287, Classes\dmSystemDB.pas:304	SQLC/SQLL/SQLD could not be obtained.	Check configuration database and connection pool state.
Microsoft XML 6.0 not installed...	Classes\vxFileDef.pas:295	XML File Definition requires MSXML 6.0.	Install Microsoft XML 6.0.
Field value conversion errors	Classes\vxFileDef.pas:422, Classes\vxFileDef.pas:438, Classes\vxFileDef.pas:454, Classes\vxFileDef.pas:470	File value cannot convert to decimal/integer.	Check source data format and field definitions.
Critical error - Invalid file type. Unable to create file engine.	Classes\vxFileDef.pas:639	File type enum not supported by factory path.	Developer/support investigation; check File Definition type.
XSD/schema errors	Classes\vxFileDef.pas:823, Classes\vxFileDef.pas:958, Classes\vxFileDef.pas:964, Classes\vxFileDef.pas:985, Classes\vxFileDef.pas:1002, Classes\vxFileDef.pas:1274, Classes\vxFileDef.pas:1341	XML schema missing, invalid, empty, duplicate/bad root fields, or namespace not cached.	Check schema path, root node, duplicate fields, and XML/XSD validity.
File missing/locked errors	Classes\vxFileCon.pas:305, Classes\vxFileCon.pas:307, Classes\vxFileCon.pas:322, Classes\vxFileCon.pas:324	Current file does not exist or is locked.	Confirm file exists and is not held by another process.
File copy/move timeout errors	Classes\vxFileCon.pas:434, Classes\vxFileCon.pas:493, Classes\vxFileCon.pas:557, Classes\vxFileCon.pas:624, Classes\vxFileCon.pas:709, Classes\vxFileCon.pas:787	File unavailable for 30 seconds.	Check locks, antivirus, share latency, source system writes.
File copy/move RaiseLastOSError and Log.Error paths	Classes\vxFileCon.pas:441, Classes\vxFileCon.pas:446, Classes\vxFileCon.pas:500, Classes\vxFileCon.pas:505, Classes\vxFileCon.pas:566, Classes\vxFileCon.pas:569, Classes\vxFileCon.pas:638, Classes\vxFileCon.pas:641, Classes\vxFileCon.pas:722, Classes\vxFileCon.pas:725, Classes\vxFileCon.pas:801, Classes\vxFileCon.pas:804	File copy/move failed; OS details supplied at runtime.	Check path, permissions, locks, disk/share availability.
Destination/audit/transport/error folder cannot be created	Classes\vxFileCon.pas:472, Classes\vxFileCon.pas:529, Classes\vxFileCon.pas:592, Classes\vxFileCon.pas:680, Classes\vxFileCon.pas:757, Classes\vxFileCon.pas:835	Directory missing and create failed.	Check folder path and service account permissions.
Velox (...) has unassigned DB Connection on thread ... (FreeCons)	Classes\vxConPool.pas:540	Connection pool state corruption/unassigned DB connection.	Developer/support investigation.

Modules, Maps, Reports, APIs, And OpenAPI

Important classes: TvxModule, TvxMap, TvxReport, TvxAPI.

Message or exception expression	Source	Cause	Recovery/user guidance
Module not found exceptions	Classes\vxModule.pas:1543, Classes\vxModule.pas:1545, Classes\vxModule.pas:1614, Classes\vxModule.pas:1650	Module lookup by FID/name/code returned no row.	Check deleted/archived/misconfigured module reference.
Database/program errors loading module	Classes\vxModule.pas:1577, Classes\vxModule.pas:1582, Classes\vxModule.pas:1618, Classes\vxModule.pas:1620, Classes\vxModule.pas:1654, Classes\vxModule.pas:1656	Load query or streamed module load failed.	Check DB, module stream, source exception.
Module existence/delete/create/save errors	Classes\vxModule.pas:1689, Classes\vxModule.pas:1723, Classes\vxModule.pas:1756, Classes\vxModule.pas:1830, Classes\vxModule.pas:1833, Classes\vxModule.pas:1905, Classes\vxModule.pas:1910, Classes\vxModule.pas:1948, Classes\vxModule.pas:1951, Classes\vxModule.pas:2003, Classes\vxModule.pas:2006, Classes\vxModule.pas:2080, Classes\vxModule.pas:2083	Module database operation failed.	Check DB permissions/schema and module relationships.
Map value/key mapping errors	Classes\vxMap.pas:548, Classes\vxMap.pas:569, Classes\vxMap.pas:589, Classes\vxMap.pas:647	Source value cannot map into destination field/key.	Check data types, scripts, and destination constraints.
Map lifecycle script errors	Classes\vxMap.pas:1108, Classes\vxMap.pas:1134, Classes\vxMap.pas:1149, Classes\vxMap.pas:1170, Classes\vxMap.pas:1444, Classes\vxMap.pas:1475	Before/after/on-start/on-end scripts failed.	Review script and exception detail.
Map dataview post/sync errors	Classes\vxMap.pas:1209, Classes\vxMap.pas:1352, Classes\vxMap.pas:1411, Classes\vxMap.pas:1495, Classes\vxMap.pas:1907, Classes\vxMap.pas:1945, Classes\vxMap.pas:1989, Classes\vxMap.pas:2120, Classes\vxMap.pas:2149	Destination post failed or map out of sync with data definitions.	Re-sync/edit map; verify missing/extra fields/views.
No data found to process. Processing cancelled ... (this is not an error)	Classes\vxMap.pas:2028	Empty source.	Usually expected; check source search criteria if unexpected.
Destination is populated with data...	Classes\vxMap.pas:2035	Destination was not empty before mapping.	Set destination search criteria or clear destination data.
Report no-data and no-primary-view errors	Classes\vxReport.pas:295, Classes\vxReport.pas:302, Classes\vxReport.pas:322, Classes\vxReport.pas:372, Classes\vxReport.pas:393, Classes\vxReport.pas:595, Classes\vxReport.pas:597	No data, no primary dataview, no Data Definition, or source link/load failed.	Check Report data settings and source definition.
API required-field errors	Classes\vxAPI.pas:280, Classes\vxAPI.pas:286, Classes\vxAPI.pas:292	API name/version/URL missing.	Fill required API setup fields.
API/OpenAPI creation/export/delete errors	Classes\vxAPI.pas:425, Classes\vxAPI.pas:502, Classes\vxAPI.pas:506, Classes\vxAPI.pas:543	OpenAPI schema not created, creation failed, or API action child table delete failed.	Create schema first; review exception/database state.

Transports

Important classes: base TvxTransport; FTP, SFTP, LAN, HTTP, MSMQ, IBM MQ, IMAP, POP3, SMTP, and AS2-related transport classes.

Logging: transport log through Log.Error/Log.Cancelled; user dialogs for certificate/import/test actions; Event Log for worker thread failures. Outbound send failures are retried by outbound transport manager according to transport log attempts.

Message family	Source	Cause	Recovery/user guidance
OAuth authentication errors	Classes\Transports\vxTransport.pas:464, Classes\Transports\vxTransport.pas:471, Classes\Transports\vxTransportHTTP.pas:132, Classes\Transports\vxTransportHTTP.pas:139, Classes\Tools\vxEmail.pas:365, Classes\Tools\vxEmail.pas:371	OAuth token/auth flow failed.	Check OAuth setup, client ID/secret, refresh token, authorization code, remote auth endpoint.
Host blank errors	Classes\Transports\vxTransportFTP.pas:208, Classes\Transports\vxTransportSFTP.pas:271	Transport host not configured.	Enter host/server.
File save path/name cannot be determined	Classes\Transports\vxTransport.pas:836, Classes\Transports\vxTransport.pas:856, Classes\Transports\vxTransport.pas:877	File Connection filename/pattern/save path missing or invalid.	Configure File Connection filename/pattern/directories.
Unable to create transport save folder	Classes\Transports\vxTransport.pas:843, Classes\Transports\vxTransport.pas:864	Folder create failed.	Check service account permissions.
Inbound/outbound transport final execution failure	Classes\Transports\vxTransport.pas:951, Classes\Transports\vxTransport.pas:959, Classes\Transports\vxTransport.pas:1015, Classes\Transports\vxTransport.pas:1023	Transport run ended Error or unhandled exception.	Inspect transport log and remote exception.
No test file / no file / current filename not found	Classes\Transports\vxTransportFTPOut.pas:208, Classes\Transports\vxTransportFTPOut.pas:211, Classes\Transports\vxTransportFTPOut.pas:215, similar in SFTP/LAN/HTTP/MSMQ/IBM MQ/SMTP out classes	Test/send source file missing.	Ensure file exists in process folder and pattern matches.
FTP connect/list/upload/delete/move/disconnect errors	Classes\Transports\vxTransportFTP.pas, Classes\Transports\vxTransportFTPIn.pas, Classes\Transports\vxTransportFTPOut.pas	FTP server/path/credentials/file operation failed.	Check host, credentials, path case, network, and remote folder permissions.
SFTP key/security errors	Classes\Transports\vxTransportSFTP.pas:395, Classes\Transports\vxTransportSFTP.pas:453, Classes\Transports\vxTransportSFTP.pas:459, Classes\Transports\vxTransportSFTP.pas:466, Classes\Transports\vxTransportSFTP.pas:486	Missing private key, public key mismatch, public key not loaded, or key save failed.	Verify certificate cache, accept/download current server key, check private key file.
SFTP connect/list/download/upload/delete/move/disconnect errors	Classes\Transports\vxTransportSFTP.pas, Classes\Transports\vxTransportSFTPIn.pas, Classes\Transports\vxTransportSFTPOut.pas	SFTP operation failed.	Check host, credentials, path case, keys, remote permissions.
LAN shared-folder errors	Classes\Transports\vxTransportLANIn.pas, Classes\Transports\vxTransportLANOut.pas	UNC path missing, file locked, copy/move/send failed.	Check share path, service account permissions, locks.
HTTP upload/download response-code errors	Classes\Transports\vxTransportHTTPIn.pas, Classes\Transports\vxTransportHTTPOut.pas	HTTP server returned non-success response or request exception.	Check endpoint, auth, headers/body, remote response code/text.
POP/IMAP mailbox errors	Classes\Transports\vxTransportPOP.pas, Classes\Transports\vxTransportIMAP.pas	Connect/list/download/open/read/delete/move/disconnect failed.	Check mailbox, credentials, TLS, host, folder names, message search pattern.
SMTP email send errors	Classes\Transports\vxTransportSMTP.pas:362, Classes\Tools\vxEmail.pas:387, Classes\Tools\vxEmail.pas:430, Classes\Tools\vxEmail.pas:436	Email send failed or SMTP/from address missing.	Configure SMTP server/from address and recipients.
MSMQ errors	Classes\Transports\vxTransportMSMQ.pas, Classes\Transports\vxTransportMSMQIn.pas, Classes\Transports\vxTransportMSMQOut.pas	Connect/list/download/upload/disconnect failed.	Check MSMQ host, queue, permissions, service availability.
IBM MQ completion/reason-code errors	Classes\Transports\vxTransportIBMMQ.pas, Classes\Transports\vxTransportIBMMQIn.pas, Classes\Transports\vxTransportIBMMQOut.pas	IBM MQ connection/open/download/upload/close/disconnect returned MQ code or exception.	Use logged completion/reason code, host, queue, credentials, MQ service state.
Transport custom script compile/runtime errors	Classes\Transports\vxTransport.pas:723, Classes\Transports\vxTransport.pas:739	Transport script failed.	Correct script.
Certificate/key generation/import errors	Classes\Transports\vxTransport.pas:614, Classes\Transports\vxTransport.pas:1240, Classes\Transports\vxTransport.pas:1255	Certificate generation/import failed or duplicate key exists.	Check certificate cache and key name.

Service Managers, Worker Threads, And Services

Important classes/services: VeloxService, VeloxAPIService, TvxScheduleManager, TvxMonitorManager, TvxRESTManager, transport managers, TActionThread, TRESTActionThread, TTransportInActionThread, TTransportOutActionThread, TvxExecutionItem.

Message or status	Source	Cause	Recovery/user guidance
Configuration database connect errors	VeloxService\classMain.pas:159, VeloxService\classMain.pas:168, VeloxAPIService\classMain.pas:172, VeloxAPIService\classMain.pas:181	Service cannot connect to config DB.	Check Connections.json, DB availability, credentials, service account network rights.
Service configuration load errors	VeloxService\classMain.pas:247, VeloxService\classMain.pas:266, VeloxAPIService\classMain.pas:231, VeloxAPIService\classMain.pas:242	Setup/managers failed loading.	Check system logs and restart service after fixing config.
Service shutdown/freeing errors	VeloxService\classMain.pas:299, :314, :334, :344, :361, :378, :389, :406, :421, :440; API service equivalents in VeloxAPIService\classMain.pas	Stop/shutdown cleanup failed.	Check stuck threads, connection pools, COM cleanup, and event log.
Install/uninstall errors	VeloxService\classMain.pas:768, :774, VeloxAPIService\classMain.pas:483, :489	Windows service install/uninstall failed.	Run with admin rights, check service name/account.
Missing -c config key or -n display name	VeloxService\classMain.pas:845, :900, VeloxAPIService\classMain.pas:658, :682	Required service command-line parameter missing.	Fix service command line/install config.
API web-server bind/start errors	VeloxAPIService\classMain.pas:151, :159, :261	Port bind/start failed.	Check port in use, firewall, permissions, configured port.
Scheduled/monitor/REST manager sync errors	Classes\Service\vxManagerScheduler.pas:608, :644, :653, :743; vxManagerMonitor.pas:470, :506, :514, :535, :576, :604; vxManagerREST.pas:351, :387, :396, :455	Manager could not load or synchronize configured Flow.	Check Flow active state, execution type, file connection/endpoint settings, module load errors.
Monitor folder errors	Classes\Service\vxManagerMonitor.pas:158, :240, :300, :306	Folder missing/cannot create, directory watcher error, file connection missing.	Check directory path, service account permissions, File Connection assignment.
Schedule interval error	Classes\Service\vxManagerScheduler.pas:337	Calculated interval is <= 0.	Check schedule settings/time window.
Worker thread critical load errors	Classes\Service\vxActionThread.pas:181, :186, :652, :658	Action missing/not loaded.	Check Flow module exists and service sync state.
Worker thread unhandled exceptions	Classes\Service\vxActionThread.pas:218, :226, :413, :423, :553, :574, :688, :696	Unhandled exception in action/transport thread.	Review exception stack and the Flow/transport log.
Connection cleanup errors	Classes\Service\vxActionThread.pas:237, :247, :434, :445, :585, :593, :707, :717, Classes\Service\vxManagerExecution.pas:486, :496	DB/system connection pool release failed.	Developer/support investigation; inspect pool state.
Transport manager sync/load errors	Classes\Service\vxManagerTransportIn.pas, Classes\Service\vxManagerTransportOut.pas	Transport manager could not load Flow/transport or process outbound queue.	Check transport config, Flow links, log transport records.
System time change reload failure	VeloxService\classMain.pas:961	Scheduled action reload after system time change failed.	Restart VeloxService as message instructs.

API Service And REST Endpoint Errors

Important classes: TvxRESTManager, TvxRESTItem, TRESTActionThread, TRESTModule.

Message/status	Source	Cause	Recovery/user guidance
503 / The API endpoint is unavailable right now. Please try again later.	Classes\Service\vxManagerREST.pas:116	REST item disabled.	Check API Flow active/configuration and REST manager sync.
Invalid Flow FID, 500	VeloxAPIService\vxWebModule.pas:124, :131	Deprecated/direct FID path received invalid GUID/FID.	Provide valid Flow GUID if using that path.
Fatal exception from REST action thread	Classes\Service\vxManagerREST.pas:156, :159, :221, :224	REST worker thread fatal exception.	Inspect service/system log and Flow log; HTTP status uses configured server-error code if action assigned.
REST Flow Error/Issue client-error mapping	Classes\Service\vxManagerREST.pas:164, :228, :229	Flow log status Error; POST also maps Issue to client error.	Inspect problem JSON/log and correct request or Flow config.
Generic REST execution error	Classes\Service\vxManagerREST.pas:172, :173, :238, :239	Thread finished without assigned action or unexpected condition.	Check service logs and endpoint Flow.
REST timeout 500	Classes\Service\vxManagerREST.pas:177, :178, :243, :244	REST item waited five minutes and action thread did not finish.	Investigate long-running Flow, thread pool, external dependencies.
Default endpoint listing error 500	Classes\Service\vxManagerREST.pas:544, :545	Error listing API services.	Check config DB and REST manager.
No API Flow configured for endpoint 500	Classes\Service\vxManagerREST.pas:597, :598	Requested path not in endpoint dictionary.	Check REST endpoint path and active API Flow config.
Deprecated ExecuteRESTItemForFID loading errors	Classes\Service\vxManagerREST.pas:660, :669	Direct REST Flow by FID failed to load.	Prefer endpoint path; check Flow load.

Designer UI, Forms, And Tools

Important classes/forms: vxMessages, tree nodes, setup forms, log managers, update password/transport utilities, schema outliners, service manager UI, IPC client, timer/service/file/tag tools.

Message family	Source	Cause	Recovery/user guidance
Configuration template import/export errors	Forms\frmConfigTemplateImporter.pas:640, :653, :660, Classes\vxConfigTemplate.pas:99, :439, Classes\vxModule.pas:4284	Template file invalid/corrupt/empty or export module invalid.	Verify template file and loaded modules before export/import.
XSD/schema UI errors	Forms\frmCreateXSD.pas:61, :67, :74, :96, :100, Classes\GUI\vxXMLSchemaOutliner.pas, Classes\vxXMLEngine.pas	Missing folder/name, invalid XML/XSD, root node missing.	Validate XML/XSD, choose folder/file/root.
Manage/list/delete/display errors	Forms\frmManageActions.pas, frmManageMaps.pas, frmManageTransports.pas, frmManageLogs.pas, frmManageTransportLogs.pas, frmViewProcesses.pas, Classes\GUI\vxTreeNodes.pas	Database/list/form/delete operation failed.	Check exception details, DB connection, module state.
Setup save/test errors	Forms\frmSetupActions.pas:484, frmSetupAPI.pas:385, frmSetupDBCon.pas:267, :271, frmSetupFileCon.pas:229, frmSetupGeneral.pas, frmSetupMapDesign.pas:1004, frmSetupReports.pas:141, frmSetupScriptlet.pas:181, frmSetupSQLScript.pas:262	User setup save/test failed.	Correct fields and inspect exception.
Service control UI errors	Forms\frmMain.pas:1459, :1476, :1496, :1509, :1524, :1538, Forms\frmSetupGeneral.pas:659, :675, :695, :711	Service start/stop/restart failed.	Check Windows service status, account, event log.
IPC client errors	Classes\Tools\vxIPC.pas:140, :144, :173, :177, :214, :245, :275, :305, :333, :337, :367, :371, :401, :405, :435, :439, :479, :483	Designer could not communicate with service or service rejected request.	Check service running, IPC server, requested Flow, FIPCClient.LastError.
Timer errors	Classes\Tools\vxTimer.pas:105, :117, :175, :182, :191, :198, :207, :235	Windows timer queue/event failed or timer misused.	Restart service/app; developer review if repeated.
Windows service helper errors	Classes\Tools\vxService.pas	SCM operations failed; exact code from Windows.	Use Windows error code/message; check admin rights, service name/account.
Tag processing errors	Classes\Tools\vxTags.pas:79, :258, :261, :269, :302, :306, :312, :380, :383, :391	Invalid tag, missing dataview/field/variable group/variable.	Correct tag format and referenced objects.
Shell/file/script utility errors	Classes\Tools\vxShell.pas, vxFiles.pas, vxScriptFiles.pas, vxHash.pas, vxLateBinding.pas, vxXMLTransform.pas	OS/file/shell/hash/DLL/XML transform failure.	Check path, permissions, external process, DLL availability, XML validity.

Exception Handling And Recovery Principles

Configuration Errors

Common message cues:

• Please check your configuration.
• has not been assigned
• not configured
• not found in the database
• Connections.json

Recovery:

• Edit the referenced Flow/module/data definition/transport.
• Re-save the module so relation links are updated.
• If the service executes the item, resync/restart service after changing runtime config when required.

External System Errors

Common message cues:

• Error connecting to
• Error uploading
• Error downloading
• HTTP response code/text
• IBM MQ completion/reason code
• mailbox, queue, FTP/SFTP/HTTP/shared-folder wording

Recovery:

• Check network, remote server availability, credentials, certificates/keys, paths, queue names, and account permissions.
• Use the logged exception text or protocol code.
• For outbound transport sends, check VX_LOG_TRANSPORT attempt count and next attempt date.

File Stability Errors

Common message cues:

• does not exist
• is locked
• Time-out (30 secs) waiting for file
• could not be created

Recovery:

• Check source system file-write behavior, file locks, antivirus, network share latency, and Velox service account rights.
• Ensure monitor folders and audit/error/transport folders exist or can be created.

Program/Critical Errors

Common message cues:

• critical error
• Program error
• Unexpected error
• connection/action pool unassigned objects

Recovery:

• Preserve log, system log, event log, and stack trace.
• Treat as developer/support investigation.
• Do not assume configuration-only recovery unless the surrounding log proves it.

Areas Where Behavior Is Unclear From Source Alone

• Runtime text for RaiseLastOSError depends on Windows error codes and cannot be fully listed from source.
• Runtime text for database, Indy, Clever Internet Suite, SecureBridge, IBM MQ, madExcept, ReportBuilder, and other third-party exceptions comes from those libraries.
• IBM MQ completion and reason code decode tables were not fully traced in this document.
• Some legacy/commented paths contain old error strings. Commented-out calls are not counted as active runtime errors.
• Ignored trial/test/backup folders such as Forms\Action can contain legacy-style error/log calls. They are not counted as active runtime errors unless a task explicitly targets those folders.