If you use the DATEdata type in your SQL code, it is likely that you have come across the “not a valid month” Oracle database error. As we shall discuss, the error can be fixed with a slight tweak of the SQL.

What is the "not a valid month" Oracle database error?

The “not a valid month” Oracle database error refers to the ORA-01843error code. This error occurs if the month portion of a DATEtype value is not a valid month. The month portion of a DATEvalue is considered not valid for one of the following reasons:

1. The month value is out of the valid range (for numeric month format)
2. The month name is misspelled (for character month format)
3. The month value is not in the proper format

The “not a valid month” error could be generated when using SQL for table data that includes a column of data type DATE, or TIMESTAMP. The error could also be generated when using SQL functions that accept a date value with a month portion as argument such as the TO_DATE, TO_TIMESTAMP, and TO_TIMESTAMP_TZfunctions. The error could also get generated due to a bug, which is not discussed in this article, and for which a bug report should be submitted.

The “not a valid month” Oracle database error is only generated for the month portion of a date not being valid. For other date-related errors, such as the day or year not being valid, other error codes are output.

This article is based on Oracle Database 19c; for earlier versions such as 12c some differences may exist. As a preliminary step, install Quest^® Toad^® for Oracle, create an instance of Oracle Autonomous Database 19c (or other), and connect to the database instance, all of which are discussed in How to download Toad for Oracle.

What are the relevant initialization parameters?

Three initialization parameters are most relevant, as discussed in the following subsections.

The NLS_DATE_FORMAT parameter

This parameter sets the default format for date values. To list the value of the parameter, run command:

select *

from nls_database_parameters

where parameter = 'NLS_DATE_FORMAT';

The output lists the default date format as DD-MON-RR:

PARAMETER                                                                      

——————————————————————————–

VALUE                                                          

—————————————————————-

NLS_DATE_FORMAT                                                                

DD-MON-RR                                                                 

It may be set explicitly at the global or session level. Here’s an example of the parameter set at the session level:

ALTER SESSION SET NLS_DATE_FORMAT = 'mm/dd/yyyy';

The NLS_TERRITORY parameter

This parameter sets the default territory, which in addition to other settings determines the default value for the NLS_DATE_FORMAT. To list the value of the parameter, run the following command to see the output shown below:

select *

from nls_database_parameters

where parameter = 'NLS_TERRITORY';

PARAMETER                                                                      

——————————————————————————–

VALUE                                                          

—————————————————————-

NLS_TERRITORY                                                                  

AMERICA                  

It may also be set explicitly at the global or session level. Here’s an example of the parameter set at the session level:

ALTER SESSION SET NLS_TERRITORY = "FRANCE";

The NLS_DATE_LANGUAGE parameter

This parameter sets the default language for day and month names in date values. To list the value of the parameter, run the following command to see the output shown below:

select *

from nls_database_parameters

where parameter = 'NLS_DATE_LANGUAGE';

PARAMETER                                                                      

——————————————————————————–

VALUE                                                          

—————————————————————-

NLS_DATE_LANGUAGE                                                              

AMERICAN

It may also be set explicitly at the global or session level. Here’s an example of the parameter set at the session level:

ALTER SESSION SET NLS_DATE_LANGUAGE = "FRENCH";

What are the valid months

Before we discuss what is not a valid month value, it is imperative to mention what the valid month values are. Different format codes for month require different values. For the MONTHformat code, valid months are: January, February, March, April, May, June, July, August, September, October, November, and December. The month value may be specified in upper/lower/mixed case.

For the MONformat code, valid month values are: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec. Again, the month value may be specified in upper/lower/mixed case.

For the MMformat code, valid month values are: 01, 02,…12.

For the RMformat code to represent a Roman numeral month, valid month values are I to XII; with Ifor January, IIfor February, and so on.

Examples – Table Data

We start off with an example using table data that does not generate the error. It is always helpful to first find which date format is in effect.

select * from nls_session_parameters where parameter = 'NLS_DATE_FORMAT';

Session altered.

PARAMETER                    

——————————

VALUE                                                          

—————————————————————-

NLS_DATE_FORMAT              

DD/MM/RR

Run an SQL query to select data from the SH.PROMOTIONStable (provided by default in most database versions). The PROMO_BEGIN_DATEcolumn value is specified in a valid format as '01/Jan/00'.

SELECT PROMO_ID, PROMO_NAME, PROMO_END_DATE FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > '01/Jan/00'

This example does not generate any error, and lists output:

PROMO_ID PROMO_NAME                     PROMO_END_DATE

———- —————————— ————–

       999 NO PROMOTION #                 01/01/99    

       49 TV promotion #12-49           10/09/00    

       42 TV promotion #13-42           22/01/01    

       82 TV promotion #13-82           06/01/01    

       101 TV promotion #12-101           17/09/00    

       141 TV promotion #12-141           23/09/00    

       172 TV promotion #12-172           26/06/00

The SQL command and output are shown in Toad for Oracle in Figure 1.

 

Figure 1. SQL Query with a valid Month value to produce an output

 

Month value not in valid range

Next, we demonstrate with an example how the “not a valid month” error could get generated if the numeric month value is out of range of 01to 12. Change the date format to 'DD-MM-YY' with command:

ALTER SESSION SET NLS_DATE_FORMAT = ‘DD-MM-YY';

Run a SQL query to select table data with a month value that is not a valid month value, such as a month value of 16. This time, the ORA-01843: not a valid montherror is generated:

SELECT PROMO_ID, PROMO_NAME, PROMO_END_DATE FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > '01-16-00' >> SELECT PROMO_ID, PROMO_NAME FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > '01-16-00'

*

Error at line 2

ORA-01843: not a valid month

The SQL command, and error message are shown in Toad for Oracle in Figure 2.

 

Figure 2. SQL Query with a month value that is out of valid range to produce a “not a valid month” error

The “not a valid month” error can be fixed easily by specifying a month value that is in the range of 01to 12, as in query:

SELECT PROMO_ID, PROMO_NAME FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > '01-01-00

As Figure 3 shows an error is not generated, and instead an SQL query output is listed.

Figure 3. SQL Query with a month value that is valid

 

Month name misspelled

If the month name is misspelled, the “not a valid month” Oracle database error gets generated. As an example, set the month format code to ‘DD-MM-YY’.

ALTER SESSION SET NLS_DATE_FORMAT = 'DD-MM-YY';

Run an SQL query with the month “Jan” misspelled as “Ja,” as in example:

SELECT PROMO_ID, PROMO_NAME FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > '30-Ja-00'

The “not a valid month” error is output:

>> SELECT PROMO_ID, PROMO_NAME FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > '30-Ja-00'

*

Error at line 4

ORA-01843: not a valid month

The SQL command and error output are shown in Figure 4.

Figure 4. SQL Query with a month value that is misspelled

The “not a valid month” error can be fixed easily by spelling the month correctly:

SELECT PROMO_ID, PROMO_NAME FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > '30-January-00'

This time an error is not generated, as indicated by query output shown in Figure 5.

 

Figure 5. SQL Query with a month value that is spelled correctly

Month value not in the proper format

Another reason for the “not a valid month” error is that it is specifying a month format that is not valid. As an example, set the date format to ‘Month-DD-YYYY’.

ALTER SESSION SET NLS_DATE_FORMAT = 'Month-DD-YYYY';

Run the following SQL query in which the month value is a numeric value of 01, whereas the date format requires a character value.

SELECT PROMO_ID, PROMO_NAME FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > '01-01-2000'

The “not a valid month” Oracle database error gets generated:

>> SELECT PROMO_ID, PROMO_NAME FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > '01-01-2000'

*

Error at line 3

ORA-01843: not a valid month

The SQL query with a month value that is not in the required format, and the error output are shown in Figure 6.

Figure 6. SQL Query with a month value that is not in the proper format

To fix the error, specify a month value that is valid such as “January”. Some conversion is built-in, and a value of “Jan” is also valid for the Monthformat code.

SELECT PROMO_ID, PROMO_NAME FROM SH.PROMOTIONS WHERE PROMO_BEGIN_DATE > 'Jan-01-2000'

As the output in Figure 7 shows an error is not generated, and instead the query output is listed.

 

Figure 7. SQL Query with a month value that is in the proper format

TO_DATE function

In the following section and subsections we shall be using the TO_DATEfunction that converts a char value provided as the first argument to a DATEvalue. Also, optionally a format for the input date value may be provided as the second function, and a language of the text string that is to be converted to a DATEvalue may be provided as the third function argument.  

We start off with an example that does not generate an error. It is always helpful to find/set the default date format, which is used for the output regardless of the input date format specified in the TO_DATEfunction call.

 

ALTER SESSION SET NLS_DATE_FORMAT = 'MM-DD-YYYY';

Run the following SQL query that includes a valid format input for the Date value:

SELECT TO_DATE(

   'Jan 22 2022',

   'Mon dd, YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL;

The SQL query output is as follows:

TO_DATE('JAN222022','MONDD,YYYY','NLS_DATE_LANGUAGE=AMERICAN')

————————————————————–

01-22-2022  

 

The SQL query and output are shown in Figure 8.

 

Figure 8. SQL Query with a valid date and month value in a TO_DATE function call

Subsequent examples demonstrate why the “not a valid month” error could get generated.

Month value out of valid range

For numeric month format, if a month value is out of range i.e., less than 01or greater than 12, the “not a valid month” Oracle database error is generated. As an example, run the following SQL query:

SELECT TO_DATE('16/02/2022',

   'MM/DD/YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL;

The “not a valid month“ error is generated:

>> SELECT TO_DATE('16/02/2022',

   'MM/DD/YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL

*

Error at line 1

ORA-01843: not a valid month

 

The SQL query and the error generated are shown in Figure 9.

 

Figure 9. SQL Query with an out of range month generates the “not a valid month” error

To fix the error, specify a numeric month value that is in the range of 01to 12, such as 02,as shown in the SQL query:

SELECT TO_DATE('02/02/2022',

   'MM/DD/YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL;

This time, the SQL query generates an output that is not an error condition as shown in Figure 10.

Figure 10. SQL Query with a valid numeric month value

Month name misspelled

If the month name in the TO_DATEfunction call is misspelled, again the “not a valid month” error is generated. As an example, run the following SQL query where “February” is misspelled:

SELECT TO_DATE('Feburary 22 2022',

   'Month dd, YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL;

The error message is:

>> SELECT TO_DATE(

   'Feburary 22 2022',

   'Month dd, YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL

*

Error at line 2

ORA-01843: not a valid month

 

The error for the preceding SQL query is shown in Figure 11.

 

Figure 11. SQL Query with a month value that is misspelled

To fix the error, fix the misspelling:

SELECT TO_DATE('February 22 2022',

   'Month dd, YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL;

As shown in Figure 12, this time the SQL query generates an output instead of an error.

 

Figure 12. SQL Query with the month value with the misspelling fixed

 

The correct spellings are based on the date language. To demonstrate, to use French spelling, set the date language to French:

SELECT TO_DATE('février 01 2022',

   'Month dd, YYYY',

     'NLS_DATE_LANGUAGE = FRENCH')

     FROM DUAL;

TO_DATE('FÉVRIER012022','MONTHDD,YYYY','NLS_DATE_LANGUAGE=FRENCH')

——————————————————————

02-01-2022  

 

The preceding SQL query, and its output are shown in Figure 13.

 

Figure 13. SQL Query with the date language as French

Month value not in the proper format

Another reason for the “not a valid month” Oracle database error is the format for the month value being incorrect. As an example, set the date format to ‘Month DD, YYYY’, but provide the month value as a numeric value as in the example:

SELECT TO_DATE(

   '02/02/2022',

   'Month DD, YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL

The error gets generated:

>> SELECT TO_DATE(

   '02/02/2022',

   'Month DD, YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL

*

Error at line 2

ORA-01843: not a valid month

 

The preceding SQL query and the error are shown in Figure 14.

 

Figure 14. SQL Query with a numeric month value when the month format expects character value

The error can be fixed by specifying a month value that matches the month format code. For the preceding example, the error is fixed as:

SELECT TO_DATE(

   'January/02/2022',

   'Month/DD/YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL

 

Fixing error with a default Date value

Another method to fix the “not a valid month” error is to provide a default return value if the error occurs, using the DEFAULT return_value ON CONVERSION ERRORclause. As an example:

 

SELECT TO_DATE('Ja 22, 2022'

       DEFAULT 'January 01, 2022' ON CONVERSION ERROR,

       'Month dd, YYYY') "Date"

FROM DUAL;

This time, the error is not generated even though the error condition exists, and the return value is the default return value in the date format set by the NLS_DATE_FORMAT:

Date    

———-

01-01-2022

 

The preceding SQL query and output are shown in Figure 15.

Figure 15. SQL Query with a default return value on conversion error

Built-in Conversion

Some implicit conversion of the DATEvalue, including the month value is built-in, or implicit. The implicit conversion could be different for different database versions. As an example a “MON” format value such as “Jan” is considered valid when the month format code is “MONTH,” which would make the valid month value as “January,” as in the example SQL query:

SELECT TO_DATE(

   'Jan 22 2022',

   'Month dd, YYYY',

     'NLS_DATE_LANGUAGE = American')

     FROM DUAL;

In this article we discussed the “not a valid month” Oracle database error; when it could get generated and how to fix it.

Related Links

Debugging PL/SQL Code with Toad for Oracle

How to use the Toad® SQL Tracker to troubleshoot issues

Getting to Know the Three Methods of Connecting to the Database Using Toad for Oracle: TNS, Direct and LDAP

Have questions about Toad Developer Tools? Click Start Discussionand this blog topic will be transferred to the Toad World Forums.