BroadSQL Download
On this page
Documentation / Troubleshooting: Error messages

Error messages

BroadSQL's own messages, grouped by subject, each with what it means, its usual causes and what to do. Parts that change from one occurrence to another are written <like this>. Every message has its own link: use "Link to this message" to share it.

The fastest way to find a message is the search: press / and paste the message. Errors that come from the database itself (a SQL syntax error, a constraint) are reported with the database's own text and SQLState; see your database's documentation for them.

Starting and connecting

No active database connection. Use CONNECT <connection> first.

What it means
You typed SQL, or a command that needs a database, while no database connection is open.
Typical causes
  • BroadSQL starts at the BroadSQL> prompt, without a connection (since 5.5.0).
  • You closed the connection with DISCONNECT, BYE or CLOSE, or ended the session with LOGOUT.
What to do
Open a connection with CONNECT <id>;. To start on a connection, pass it to the launcher (connect.bat WORLD) or set RememberLastConnection=TRUE.
See
Starting, connecting and logging out

Link to this message

Cannot connect to '<connection>': JDBC driver class '<class>' for type '<type>' was not found. Copy the matching driver .jar file into the drivers/ or lib/ folder and restart BroadSQL, then try again.

What it means
The JDBC driver of this connection's database type is not installed.
Typical causes
  • The vendor's driver JAR was never copied into drivers.
  • The JAR was copied while BroadSQL was running: drivers are found at startup.
What to do
Copy the driver JAR into drivers, restart BroadSQL, and check with SHOW DRIVERS;.
See
Connect to your database

Link to this message

Cannot switch to Environment '<environment>': <reason>

What it means
ENV could not find or open the connection of that Environment in the current Database Group. The current connection stays open.
Typical causes
  • The current connection has no Database Group (it is standalone).
  • The Environment does not exist, for example Environment 'NOPE' does not exist.
  • The Database Group has no connection for that Environment, or that connection is inactive or cannot be opened.
What to do
SHOW GROUP; lists the connections of the current Database Group by Environment; SHOW ALL ENVIRONMENTS; lists the Environments.
See
CONNECT versus ENV

Link to this message

CONNECT refused: connection '<connection>' opens the BroadSQL configuration database (CDF).

What it means
The connection's URL points to BroadSQL's own configuration database, which is never opened as an ordinary connection.
Typical causes
A connection created in an earlier release, or by hand, points to the CDF file or a copy of it.
What to do
Delete that connection with DEL CONNECTION <connection>;. For maintenance, use CONNECT $CDF at the prompt.
See
The configuration database (CDF)

Link to this message

Authentication required: enter the master password first.

What it means
The session is locked: nothing runs until the master password is typed again.
Typical causes
You ran LOGOUT (or LOGOFF).
What to do
Type the master password at the prompt.
See
Logging out

Link to this message

Production confirmation

Production change refused on connection '<connection>': the change was not confirmed. Nothing was executed. SQLState BSQPR

What it means
The connection belongs to an Environment flagged Production, the statement can change the database, and it was not confirmed. Nothing was sent to the database.
Typical causes
You answered no, gave an empty or another answer, or pressed Ctrl+C at Execute? [yes/no].
What to do
Run the statement again and answer yes (or y) if the change is intended. In a Script, the refusal stops the whole run.
See
Production confirmation

Link to this message

Production change refused on connection '<connection>': confirmation is required and no interactive confirmation is available. Nothing was executed.

What it means
BroadSQL could not ask the question, so the change to a Production database was refused. No setting turns this off.
Typical causes
BroadSQL's input is redirected from a file, or no interactive terminal is attached.
What to do
Run the change in an interactive session, or run the automated work on a connection of a non-Production Environment.
See
Without a terminal, A report Script that stops at the first failure

Link to this message

Run stopped: a Production change was refused at statement <n> of Script <name> (line <line>).

What it means
A statement of the Script was refused on a Production connection, so the whole run stopped, nested Scripts included. Statements already executed stay executed.
Typical causes
The confirmation was refused, or could not be asked.
What to do
Check what the Script already changed, then run it again and confirm, or change the Script.
See
Scripts, typed lines and the Editor

Link to this message

Scripts, arguments and variables

<script> requires argument <name> (declared in @param): pass it as name=value, or define a variable of that name with LET before the call

What it means
A required parameter of the Script received no value. No statement ran and no variable was assigned.
Typical causes
The call did not pass <name>=..., and no session variable of that name exists.
What to do
Pass it in the call, set it first with LET <name> = ...;, or give it a default in its -- @param line.
See
Where a parameter's value comes from

Link to this message

<script>: argument <name> is declared <TYPE>: <value> is <kind of value>

What it means
A value does not match the type declared by -- @param, for example argument min_population is declared INTEGER: 'many' is a text value. The Script did not start.
Typical causes
  • A number written in quotes, or text without quotes.
  • A date written in another form than 'yyyy-MM-dd'.
  • A session variable of the wrong type (the message then names it).
What to do
Write the value in the form of its type: see the conversion table.
See
Reference: conversions

Link to this message

Invalid script argument '<value>': positional script arguments (%1..%9) were removed: pass arguments as name=value and read them with ${name}

What it means
The call passed a value without a name, in the form of earlier releases.
Typical causes
A Script or a habit from before named arguments.
What to do
Name every argument (id=42) and read it in the Script as ${id}. LIB LINT; lists the %1 to %9 left in the library.
See
From %1..%9 to named arguments

Link to this message

Variable <name> is not defined.

What it means
A statement uses ${<name>}, but no variable or argument of that name exists.
Typical causes
  • A typo in the name.
  • The value was never set with LET or passed as an argument.
  • An older BroadSQL ignores @param defaults.
What to do
SHOW SCRIPT VARIABLES; lists the defined variables. Declare the parameter with -- @param, or set it with LET.
See
Variables

Link to this message

Script <name> stopped by ON ERROR STOP at statement <n> (line <line>)

What it means
The Script runs with ON ERROR STOP and a statement failed: nothing after it ran, not even a COMMIT. The status is FAILED.
Typical causes
The error printed just before this line.
What to do
Fix the failed statement, then run the Script again.
See
Error handling: ON ERROR

Link to this message

WARNING: Pending changes since the last COMMIT on <connection> were rolled back.

What it means
A statement failed with Autocommit off, so BroadSQL rolled back the pending transaction: earlier uncommitted changes are lost too.
Typical causes
  • A SQL error in a Script or at the prompt.
  • A cancelled statement that the database reported as an error.
What to do
Run the lost changes again. When changes must be kept or lost together, use ON ERROR STOP in Scripts.
See
Continuing is not keeping the transaction

Link to this message

The script <name> is written for <dialect>; the current connection's type is <type>

What it means
A warning, not an error: the Script's -- @dialect line names other database types. It runs anyway.
Typical causes
The Script was written for another database, or the wrong connection is open.
What to do
Check the connection with SHOW CONNECTION;, or correct the Script's -- @dialect line.
See
What @access and @dialect do

Link to this message

List sources

Unclosed list source '<excerpt>': a <@...> reference must end with '>' on the same line

What it means
A <@ starts a list source but its closing > is missing on that line. Nothing ran.
Typical causes
A typo, or a list source split over two lines.
What to do
Close it on the same line, for example IN <@ids.txt>.
See
Where a list source starts and ends

Link to this message

Clipboard contains multiple columns. <@clipboard> expects a single column.

What it means
A copied line holds a tab: several spreadsheet columns were copied together.
Typical causes
Two or more columns selected when copying.
What to do
Copy one column only, or read the sheet with <@excel:<file>:<sheet>:<column>>.
See
<@clipboard>

Link to this message

The system clipboard is not available: no graphical environment access to it in this session.

What it means
BroadSQL cannot reach a clipboard in this session.
Typical causes
BroadSQL runs without a graphical environment, for example over a remote terminal on Linux.
What to do
Put the values in a text file and use <@file> instead.
See
List sources

Link to this message

Export

APPEND refused: destination has <n> columns but query returns <m>. APPEND requires the same columns, with the same names, in the same order.

What it means
MODE APPEND adds rows only when the result has the destination's columns, with the same names, in the same order. Nothing was written.
Typical causes
The query returns more or fewer columns than the table or worksheet.
What to do
Select exactly the destination's columns, aliased to its names (CI.NAME AS CITY).
See
MODE APPEND

Link to this message

MERGE refused: <n> source row(s) have a NULL key (<columns>). Nothing was written.

What it means
MODE MERGE KEY identifies rows by their key, and some source rows have none.
Typical causes
A key column that can be NULL in the source, or an outer join.
What to do
Filter those rows out (WHERE <key> IS NOT NULL), or choose a key that is never NULL.
See
MODE MERGE KEY

Link to this message

DUMP LIB <script> not exported: the script finished with status <status>

What it means
DUMP LIB writes a Script's result only when the run ends with SUCCESS. Nothing was written.
Typical causes
A statement failed (COMPLETED_WITH_ERRORS or FAILED), or the run was cancelled.
What to do
Read the errors of the run above this line, fix them, and run the export again.
See
Exporting Script results

Link to this message

DUMP refused: this destination is the BroadSQL Connections Definition File ($CDF), a protected BroadSQL system database. It cannot be used as a write destination for DUMP, PULL or EXPORT. Nothing was written. Choose another destination.

What it means
The destination is BroadSQL's configuration database, which no export may write into.
Typical causes
TO $CDF.<table>, or a connection that opens the same file.
What to do
Choose another destination, for example a new local database: TO WORKCOPY.<table> AS H2.
See
The CDF is never a destination

Link to this message

Master password and configuration database

The CDF is in use by another process (possibly being upgraded). Close the other BroadSQL and start again.

What it means
Another BroadSQL has the configuration database open, possibly while upgrading it.
Typical causes
Two BroadSQL sessions started on the same installation at the same time.
What to do
Close the other BroadSQL, then start again.
See
Before installing a new release

Link to this message

The master password was NOT changed: the CDF is in use by another BroadSQL

What it means
SET MASTER PASSWORD needs the only open copy of the CDF. Nothing was changed.
Typical causes
Another BroadSQL session uses the same CDF.
What to do
Close the other sessions, then run the command again.
See
Changing the master password

Link to this message

The new master password contains a space.

What it means
The new password was refused before anything changed: the database engine could not reopen a file encrypted with it.
Typical causes
A space, or a character outside the accepted set.
What to do
Choose a password from the accepted characters, for example a long passphrase joined by symbols.
See
Accepted characters

Link to this message

An earlier master-password change was interrupted and is not resolved yet

What it means
A master-password change stopped before its end, and BroadSQL has not sorted the files out yet.
Typical causes
A crash or a power cut during SET MASTER PASSWORD.
What to do
LOGOUT;, then log in: BroadSQL completes or undoes the change.
See
Master password recovery

Link to this message

Activity log

Unable to write to log file

What it means
The activity log could not be written, and logging is off for the rest of the session.
Typical causes
The folder of LogFolderName does not exist. The Windows default, C:\BroadSQL\logs, does not exist out of the box.
What to do
Set LogFolderName=logs (the installation's own folder) or create the folder, then restart BroadSQL.
See
Command activity log

Link to this message

API Client (experimental)

No API is connected. Use CONNECT API <api>:<environment>; before RUN.

What it means
RUN needs an API session.
Typical causes
No CONNECT API was run in this session.
What to do
CONNECT API <api>:<environment>;, then RUN.
See
Running an endpoint

Link to this message

No endpoint matches: <request>

What it means
No active endpoint of the connected API has this method and path shape.
Typical causes
A typo in the path, the wrong method, or an inactive endpoint.
What to do
SHOW ENDPOINTS; lists the endpoints of the connected API.
See
Executing an inactive API, endpoint, or environment

Link to this message

Unable to resolve variable: <name>

What it means
A ${name} used by an enabled part of the request has no value.
Typical causes
  • The variable is defined at no level of the API: API, environment, folder or endpoint.
  • A difference of case: variable names are case-sensitive.
What to do
Define it in CONFIG API at the level where it belongs, with the same case as in the request.
See
Variables

Link to this message

Execution refused. Method <method> is not enabled for execution in this release.

What it means
The method, or the request body format, cannot be executed in this release.
Typical causes
A method such as OPTIONS, or a form-urlencoded or multipart-form body.
What to do
See what this release executes.
See
Executing an unsupported method or body

Link to this message

API '<api>' is inactive. <details>

What it means
The API, or its environment, was deactivated.
Typical causes
Deactivated in CONFIG API.
What to do
Reactivate it in CONFIG API.
See
Executing an inactive API, endpoint, or environment

Link to this message

DUMP API RESULT: no API execution result held in memory. Run RUN first.

What it means
There is no API result to export.
Typical causes
The last call did not succeed, or none was made.
What to do
RUN the request, then DUMP API RESULT TO <file> AS <format>;.
See
Exporting API results

Link to this message

Found something wrong or unclear on this page? , with the page address.