Oracle/PLSQL: Exception Handling

We've categorized exception handling into the following topics:

Named System Exceptions

Named Programmer-Defined Exceptions
WHEN OTHERS Clause
SQLCODE Function
SQLERRM Function
Oracle Error Messages

Oracle/PLSQL: Named System Exceptions

What is a named system exception?

Named system exceptions are exceptions that have been given

names by PL/SQL. They are named in the STANDARD package in
PL/SQL and do not need to be defined by the programmer.
Oracle has a standard set of exceptions already named as follows:
Oracle Exception Name

Oracle
Error

Explanation

DUP_VAL_ON_INDEX

ORA- You tried to execute an

00001 INSERT or UPDATE
statement that has
created a duplicate
value in a field restricted
by a unique index.

TIMEOUT_ON_RESOURCE

ORA- You were waiting for a

00051 resource and you timed
out.

TRANSACTION_BACKED_OUT ORA- The remote portion of a

00061 transaction has rolled
back.
INVALID_CURSOR

ORA- You tried to reference a

01001 cursor that does not yet

exist. This may have

happened because
you've executed a
FETCH cursor or
CLOSE cursor before
OPENing the cursor.
NOT_LOGGED_ON

ORA- You tried to execute a

01012 call to Oracle before
logging in.

LOGIN_DENIED

ORA- You tried to log into

01017 Oracle with an invalid
username/password
combination.

NO_DATA_FOUND

ORA- You tried one of the

01403 following:
1. You executed a
SELECT INTO
statement and no
rows were returned.
2. You referenced an
uninitialized row in a
table.
3.

You read past the

end of file with the
UTL_FILE package.

TOO_MANY_ROWS

ORA- You tried to execute a

01422 SELECT INTO
statement and more
than one row was
returned.

ZERO_DIVIDE

ORA- You tried to divide a

01476 number by zero.

INVALID_NUMBER

ORA- You tried to execute an

01722 SQL statement that tried
to convert a string to a
number, but it was

unsuccessful.
STORAGE_ERROR

ORA- You ran out of memory

06500 or memory was
corrupted.

PROGRAM_ERROR

ORA- This is a generic

06501 "Contact Oracle support"
message because an
internal problem was
encountered.

VALUE_ERROR

ORA- You tried to perform an

06502 operation and there was
a error on a conversion,
truncation, or invalid
constraining of numeric
or character data.

CURSOR_ALREADY_OPEN

ORA- You tried to open a

06511 cursor that is already
open.

The syntax for the Named System Exception in a procedure is:

CREATE [OR REPLACE] PROCEDURE procedure_name
[ (parameter [,parameter]) ]
IS
[declaration_section]
BEGIN
executable_section
EXCEPTION
WHEN exception_name1 THEN
[statements]
WHEN exception_name2 THEN
[statements]
WHEN exception_name_n THEN
[statements]

WHEN OTHERS THEN

[statements]
END [procedure_name];
The syntax for the Named System Exception in a function is:
CREATE [OR REPLACE] FUNCTION function_name
[ (parameter [,parameter]) ]
RETURN return_datatype
IS | AS
[declaration_section]
BEGIN
executable_section
EXCEPTION
WHEN exception_name1 THEN
[statements]
WHEN exception_name2 THEN
[statements]
WHEN exception_name_n THEN
[statements]
WHEN OTHERS THEN
[statements]
END [function_name];
Here is an example of a procedure that uses a Named System
Exception:
CREATE OR REPLACE PROCEDURE add_new_supplier
(supplier_id_in IN NUMBER, supplier_name_in
IN VARCHAR2)

IS
BEGIN
INSERT INTO suppliers (supplier_id,
supplier_name )
VALUES ( supplier_id_in, supplier_name_in );
EXCEPTION
WHEN DUP_VAL_ON_INDEX THEN
raise_application_error (-20001,'You have
tried to insert a duplicate supplier_id.');
WHEN OTHERS THEN
raise_application_error (-20002,'An error
has occurred inserting a supplier.');
END;
In this example, we are trapping the Named System Exception
called DUP_VAL_ON_INDEX. We are also using the WHEN
OTHERS clause to trap all remaining exceptions.

Oracle/PLSQL: Named Programmer-Defined

Exceptions
What is a named programmer-defined exception?
Sometimes, it is necessary for programmers to name and trap their own
exceptions - ones that aren't defined already by PL/SQL. These are called
Named Programmer-Defined Exceptions.
The syntax for the Named Programmer-Defined Exception in a procedure is:
CREATE [OR REPLACE] PROCEDURE procedure_name
[ (parameter [,parameter]) ]
IS
[declaration_section]
exception_name EXCEPTION;
BEGIN
executable_section
RAISE exception_name;
EXCEPTION
WHEN exception_name THEN
[statements]
WHEN OTHERS THEN
[statements]
END [procedure_name];
The syntax for the Named Programmer-Defined Exception in a function is:
CREATE [OR REPLACE] FUNCTION function_name

[ (parameter [,parameter]) ]
RETURN return_datatype
IS | AS
[declaration_section]
exception_name EXCEPTION;
BEGIN
executable_section
RAISE exception_name;
EXCEPTION
WHEN exception_name THEN
[statements]
WHEN OTHERS THEN
[statements]
END [function_name];
Here is an example of a procedure that uses a Named Programmer-Defined
Exception:
CREATE OR REPLACE PROCEDURE add_new_order
(order_id_in IN NUMBER, sales_in IN NUMBER)
IS
no_sales EXCEPTION;
BEGIN
IF sales_in = 0 THEN
RAISE no_sales;
ELSE
INSERT INTO orders (order_id,
total_sales )
VALUES ( order_id_in, sales_in );
END IF;

EXCEPTION
WHEN no_sales THEN
raise_application_error (-20001,'You must
have sales in order to submit the order.');
WHEN OTHERS THEN
raise_application_error (-20002,'An error
has occurred inserting an order.');
END;
In this example, we have declared a Named Programmer-Defined Exception
called no_sales in our declaration statement with the following code:
no_sales EXCEPTION;
We've then raised the exception in the executable section of the code:
IF sales_in = 0 THEN
RAISE no_sales;
Now if the sales_in variable contains a zero, our code will jump directly to
the Named Programmer-Defined Exception called no_sales.
Finally, we tell our procedure what to do when the no_sales exception is
encountered by including code in the WHEN clause:
WHEN no_sales THEN
raise_application_error (-20001,'You must
have sales in order to submit the order.');
We are also using the WHEN OTHERS clause to trap all remaining
exceptions:
WHEN OTHERS THEN
raise_application_error (-20002,'An error has
occurred inserting an order.');

Oracle/PLSQL: WHEN OTHERS Clause

What is a WHEN OTHERS clause?
The WHEN OTHERS clause is used to trap all remaining exceptions
that have not been handled by your Named System
Exceptionsand Named Programmer-Defined Exceptions.
The syntax for the WHEN OTHERS clause in a procedure is:
CREATE [OR REPLACE] PROCEDURE procedure_name
[ (parameter [,parameter]) ]
IS
[declaration_section]
BEGIN
executable_section
EXCEPTION
WHEN exception_name1 THEN
[statements]
WHEN exception_name2 THEN
[statements]
WHEN exception_name_n THEN
[statements]
WHEN OTHERS THEN
[statements]
END [procedure_name];
The syntax for the WHEN OTHERS clause in a function is:

CREATE [OR REPLACE] FUNCTION function_name

[ (parameter [,parameter]) ]
RETURN return_datatype
IS | AS
[declaration_section]
BEGIN
executable_section
EXCEPTION
WHEN exception_name1 THEN
[statements]
WHEN exception_name2 THEN
[statements]
WHEN exception_name_n THEN
[statements]
WHEN OTHERS THEN
[statements]
END [function_name];
Here is an example of a procedure that uses a WHEN OTHERS
clause:
CREATE OR REPLACE PROCEDURE add_new_order
(order_id_in IN NUMBER, sales_in IN NUMBER)
IS
no_sales EXCEPTION;
BEGIN
IF sales_in = 0 THEN
RAISE no_sales;
ELSE
INSERT INTO orders (order_id,
total_sales )

VALUES ( order_id_in, sales_in );

END IF;
EXCEPTION
WHEN DUP_VAL_ON_INDEX THEN
raise_application_error (-20001,'You have
tried to insert a duplicate order_id.');
WHEN no_sales THEN
raise_application_error (-20001,'You must
have sales in order to submit the order.');
WHEN OTHERS THEN
raise_application_error (-20002,'An error
has occurred inserting an order.');
END;
In this example, if an exception is encountered that is not
a DUP_VAL_ON_INDEX or a no_sales, it will be trapped by the
WHEN OTHERS clause.

Frequently Asked Questions

Question: Is there any way to get the ORA error number (and/or
description) for the errors that will fall into OTHERS?
Something like:
WHEN OTHERS THEN
'Error number ' & Err.Number & ' has
happened.'
Answer: Yes, you can use SQLCODE function to retrieve the error number
and SQLERRM function to retrieve the error message.
For example, you could raise the error as follows:
EXCEPTION
WHEN OTHERS THEN
raise_application_error(-20001,'An error
was encountered - '||SQLCODE||' -ERROR- '||
SQLERRM);
END;
Or you could log the error to a table as follows:
EXCEPTION
WHEN OTHERS THEN
err_code := SQLCODE;
err_msg := substr(SQLERRM, 1, 200);
INSERT INTO audit_table (error_number,
error_message)
VALUES (err_code, err_msg);
END;

What does the SQLCODE Function do?

The SQLCODE function returns the error number associated with the
most recently raised error exception. This function should only be
used within the Exception Handling section of your code:
EXCEPTION
WHEN exception_name1 THEN
[statements]
WHEN exception_name2 THEN
[statements]
WHEN exception_name_n THEN
[statements]
WHEN OTHERS THEN
[statements]
END [procedure_name];
You could use the SQLCODE function to raise an error as follows:
EXCEPTION
WHEN OTHERS THEN
raise_application_error(-20001,'An error
was encountered - '||SQLCODE||' -ERROR- '||
SQLERRM);
END;
Or you could log the error to a table as follows:
EXCEPTION
WHEN OTHERS THEN
err_code := SQLCODE;
err_msg := substr(SQLERRM, 1, 200);

INSERT INTO audit_table (error_number,

error_message)
VALUES (err_code, err_msg);
END;

Oracle/PLSQL: SQLERRM Function

What does the SQLERRM Function do?
The SQLERRM function returns the error message associated with
the most recently raised error exception. This function should only be
used within the Exception Handling section of your code:
EXCEPTION
WHEN exception_name1 THEN
[statements]
WHEN exception_name2 THEN
[statements]
WHEN exception_name_n THEN
[statements]
WHEN OTHERS THEN
[statements]
END [procedure_name];
You could use the SQLERRM function to raise an error as follows:
EXCEPTION
WHEN OTHERS THEN
raise_application_error(-20001,'An error
was encountered - '||SQLCODE||' -ERROR- '||
SQLERRM);
END;
Or you could log the error to a table as follows:
EXCEPTION
WHEN OTHERS THEN
err_code := SQLCODE;
err_msg := substr(SQLERRM, 1, 200);

INSERT INTO audit_table (error_number,

error_message)
VALUES (err_code, err_msg);
END;

Oracle/PLSQL: Oracle Error Messages

The following is a listing of Oracle Error Messages:
00001-00899

00900-00999
01000-01399
01400-01499
01500-01999
02000-06499
06500-09999
10000 - 12999

Eg:
Oracle/PLSQL: ORA-00001 Error
Error Message
ORA-00001: unique constraint
(constraint_name) violated
Cause of Error
You tried to execute an INSERT or UPDATE
statement that has created a duplicate value in a
field restricted by a unique index.

Resolution
The option(s) to resolve this Oracle error are:
Option #1
Drop the unique constraint.
Option #2
Change the constraint to allow duplicate values.
Option #3
Modify your SQL so that a duplicate value is not
created.
Note
If you are not sure which unique constraint was
violated, you can run the following SQL:
select distinct table_name
from all_indexes
where index_name =
'CONSTRAINT_NAME';

In our example (see picture above), our

constraint name would be SYS_C002459 and
we would execute the following SQL:
select distinct table_name
from all_indexes
where index_name = 'SYS_C002459';
This would return the name of the table whose
unique constraint we violated.