NatSpec: oz-upgrades-unsafe-allow argument not recognized


I am getting the following error:

deploy_contract$ npx truffle migrate --network testnet

Compiling your contracts...
> Compiling ./contracts/Box.sol
> Compiling @openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol
> Compiling @openzeppelin/contracts-upgradeable/security/PausableUpgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/token/ERC20/extensions/ERC20BurnableUpgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/token/ERC20/extensions/IERC20MetadataUpgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/utils/AddressUpgradeable.sol
> Compiling @openzeppelin/contracts-upgradeable/utils/ContextUpgradeable.sol
> Artifacts written to /home/deploy_contract/build/contracts
> Compiled successfully using:
   - solc: 0.8.6+commit.11564f7e.Emscripten.clang

Starting migrations...
> Network name:    'testnet'
> Network id:      1001
> Block gas limit: 999999999999 (0xe8d4a50fff)


Exiting: Review successful transactions manually by checking the transaction hashes above on Etherscan.

Error: NatSpec: oz-upgrades-unsafe-allow argument not recognized:
    at /home/deploy_contract/node_modules/@openzeppelin/upgrades-core/src/validate/run.ts:102:15

:1234: Code to reproduce

// contracts/Box.sol
// SPDX-License-Identifier: MIT
pragma solidity 0.8.6;

contract Box {
    uint256 private value;

    // Emitted when the stored value changes
    event ValueChanged(uint256 newValue);

    // Stores a new value in the contract
    function store(uint256 newValue) public {
        value = newValue;
        emit ValueChanged(newValue);

    // Reads the last stored value
    function retrieve() public view returns (uint256) {
        return value;

// migrations/2_deploy_box.js
const Box = artifacts.require('Box');

const { deployProxy } = require('@openzeppelin/truffle-upgrades');

module.exports = async function (deployer) {
  await deployProxy(Box, [42], { deployer, initializer: 'store' });

:computer: Environment

npx truffle version Truffle v5.5.20 (core: 5.5.20) Ganache v7.2.0 Solidity - 0.8.6 (solc-js) Node v16.15.1 Web3.js v1.7.4

npm list
deploy_contract@1.0.0 /home/kevin/proground/deploy_contract
├── @openzeppelin/contracts-upgradeable@4.7.0
├── @openzeppelin/contracts@4.7.0
├── @openzeppelin/truffle-upgrades@1.15.0
├── caver-js-ext-kas@1.11.0
├── truffle-hdwallet-provider-klaytn@1.4.1
└── truffle@5.5.20

I've tried different solc versions but that did not solve the problem.
It is strange because in my other computer I've managed to deploy the proxy.
I'm using a Windows11 with wsl2 Ubuntu 20.04 LTS

Thanks in advanced.


Hi @kevinnn, are there other contracts in your project that may have a NatSpec comment with tag oz-upgrades-unsafe-allow? Or could that be present in previously built contracts? (e.g. try deleting the build directory).

We've identified an issue where having that tag without arguments could cause the error that you are seeing. The workaround would be to remove the tag if it isn't needed, or to include one of the checks as a tag argument if that check needs to be disabled.


Thanks for helping me out.
I was initially working with an openzeppelin-wizard-generated transparent proxy contract and it had 'oz-upgrades-unsafe-allow'.
I removed everything within /build and tried again with Box (the code above) and it worked! (Thanks!!)

And with my original ERC20 contract,
this was my code that I copied/pasted from OZ wizard.

contract MyToken is Initializable, ERC20Upgradeable, ERC20BurnableUpgradeable, PausableUpgradeable, OwnableUpgradeable {
    /// @custom:oz-upgrades-unsafe-allow constructor 
    constructor() {

From your hint, I found that the issue happened due to the extra whitespace at the end of this line:

    /// @custom:oz-upgrades-unsafe-allow constructor 

I must have copied it and accidently (no idea why/how) added the whitespace at the end.
That was why it could not find the argument I guess.

Problem solved!!

Thanks again!


1 Like