throw

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

A declaração throw lança uma exceção definida pelo usuário. A execução da função atual vai parar (as instruções após o throw não serão executadas), e o controle será passado para o primeiro bloco catch na pilha de chamadas. Se nenhum bloco catch existe entre as funções "chamadoras", o programa vai terminar.

Sintaxe

throw expressão;
expressão

A expressão a ser lançada.

Descrição

Use a instrução throw para lançar uma exceção. Quando você lança uma exceção, expressão especifica o valor da exceção. Cada uma das intruções a seguir lança uma exceção:

js
throw "Erro2"; // gera uma exceção com um valor string
throw 42; // gera uma exceção com o valor 42
throw true; // gera uma exceção com o valor true

Note também que a instrução throw é afetada pela inserção automática de ponto-e-vírgula (ASI) como nenhum terminador de linha entre a palavra throw e a expressão é permitido.

Exemplos

Lançando um objeto

Você pode especificar um objeto quando você lança uma exceção. Você pode então referenciar as propriedades do objeto no bloco catch. O exemplo a seguir cria um objeto do tipo UserException e o usa na intrução throw.

js
function UserException(message) {
  this.message = message;
  this.name = "UserException";
}
function getMonthName(mo) {
  mo = mo - 1; // Ajusta o número do mês para index de array (1=Jan, 12=Dec)
  var months = [
    "Jan",
    "Feb",
    "Mar",
    "Apr",
    "May",
    "Jun",
    "Jul",
    "Aug",
    "Sep",
    "Oct",
    "Nov",
    "Dec",
  ];
  if (months[mo] !== undefined) {
    return months[mo];
  } else {
    throw new UserException("InvalidMonthNo");
  }
}

try {
  // statements to try
  var myMonth = 15; // 15 is out of bound to raise the exception
  monthName = getMonthName(myMonth);
} catch (e) {
  monthName = "unknown";
  logMyErrors(e.message, e.name); // pass exception object to err handler
}

Outro exemplo lançando um objeto

O exemplo a seguir testa uma string de entrada para um cep dos Estados Unidos. Se o CEP utiliza um formato inválido, a intrução throw lança uma exceção através da criação de um objeto do tipo ZipCodeFormatException.

js
/*
 * Cria um objeto ZipCode.
 *
 * Formatos aceitos para o CEP são:
 *    12345
 *    12345-6789
 *    123456789
 *    12345 6789
 *
 * Se o argumento passado para o construtor do ZipCode não atende
 * a um desses padrões uma exceção é lançada.
 */

function ZipCode(zip) {
  zip = new String(zip);
  pattern = /[0-9]{5}([- ]?[0-9]{4})?/;
  if (pattern.test(zip)) {
    // o valor do CEP será a primeira combinação na string
    this.value = zip.match(pattern)[0];
    this.valueOf = function () {
      return this.value;
    };
    this.toString = function () {
      return String(this.value);
    };
  } else {
    throw new ZipCodeFormatException(zip);
  }
}

function ZipCodeFormatException(value) {
  this.value = value;
  this.message = "does not conform to the expected format for a zip code";
  this.toString = function () {
    return this.value + this.message;
  };
}

/*
 * Isso poderia estar em um script que valida dados de endereços
 * para os endereços dos Estados Unidos.
 */

const ZIPCODE_INVALID = -1;
const ZIPCODE_UNKNOWN_ERROR = -2;

function verifyZipCode(z) {
  try {
    z = new ZipCode(z);
  } catch (e) {
    if (e instanceof ZipCodeFormatException) {
      return ZIPCODE_INVALID;
    } else {
      return ZIPCODE_UNKNOWN_ERROR;
    }
  }
  return z;
}

a = verifyZipCode(95060); // retorna 95060
b = verifyZipCode(9560); // retorna -1
c = verifyZipCode("a"); // retorna -1
d = verifyZipCode("95060"); // retorna 95060
e = verifyZipCode("95060 1234"); // retorna 95060 1234

Relançando uma exceção

Você pode usar throw para relançar uma exceção após você pegá-la. O exemplo a seguir pega uma exceção com um valor numérico e a relança se o valor for maior que 50. A exceção relançada propaga para a função encapsuladora ou para o nível superior para que o usuário a veja.

js
try {
  throw n; // lança uma exceção com um valor numérico
} catch (e) {
  if (e <= 50) {
    // instruções para tratar exceções 1-50
  } else {
    // não pode tratar esta exceção então relança
    throw e;
  }
}

Especificações

Specification
ECMAScript® 2025 Language Specification
# sec-throw-statement

Compatibilidade com navegadores

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
throw

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

Veja também