Missing or incorrect permissions

Oct 13, 2025 by wbrum.org 111 views

Introduction

As a developer, migrating your Google Chrome extension from Manifest 2 to 3 can be a daunting task. With the introduction of Manifest V3, Google has made significant changes to the way extensions interact with the browser. One of the common issues that developers face during this migration process is the "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error. In this article, we will discuss the causes and solutions to this error, and provide a step-by-step guide on how to resolve it.

Understanding the Error

The "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error occurs when the browser tries to access a property of an object that is undefined. In the context of Chrome extensions, this error is often caused by the way the extension interacts with the browser's storage API.

Causes of the Error

There are several reasons why you might encounter this error when migrating your extension from Manifest 2 to 3. Some of the common causes include:

Incorrect usage of chrome.storage API: The chrome.storage API has undergone significant changes in Manifest V3. If you are using the API incorrectly, you might encounter this error.
Missing or incorrect permissions: In Manifest V3, you need to specify the permissions required by your extension in the manifest file. If you have missed or incorrectly specified the permissions, you might encounter this error.
Incompatible extension code: If your extension code is not compatible with Manifest V3, you might encounter this error.

Solutions to the Error

To resolve the "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error, you need to identify and fix the underlying cause. Here are some solutions to get you started:

1. Check the chrome.storage API usage

In Manifest V3, the chrome.storage API has undergone significant changes. You need to use the chrome.storage.local or chrome.storage.sync API instead of chrome.storage. Here's an example of how to use the chrome.storage.local API:

chrome.storage.local.get('key', function(result) {
  console.log(result);
});

2. Specify the correct permissions

In Manifest V3, you need to specify the permissions required by your extension in the manifest file. Make sure to include the storage permission in the manifest file:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "permissions": ["storage"]
}

3. Update the extension code

If your extension code is not compatible with Manifest V3, you need to update it to use the new APIs and features. Here are some examples of how to update your extension code:

Use the new chrome.storage API: As mentioned earlier, you need to use the chrome.storage.local or chrome.storage.sync API instead of chrome.storage.
Use the new chrome.tabs API: In Manifest V3, the chrome.tabs API has undergone significant changes. You need to use the chrome.tabs.query method instead of chrome.tabs.getAllInWindow.
Use the new chrome.runtime API: In Manifest V3, the chrome.runtime API has undergone significant changes. You need to use the chrome.runtime.getURL method instead of chrome.runtime.getManifest.

Example Use Cases

Here are some example use cases that demonstrate how to resolve the "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error:

Example 1: Using the chrome.storage API

chrome.storage.local.get('key', function(result) {
  console.log(result);
});

Example 2: Specifying the correct permissions

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "permissions": ["storage"]
}

Example 3: Updating the extension code

// Use the new chrome.storage API
chrome.storage.local.get('key', function(result) {
  console.log(result);
});
// Use the new chrome.tabs API
chrome.tabs.query( active true, currentWindow: true , function(tabs) {
console.log(tabs);
});
// Use the new chrome.runtime API
chrome.runtime.getURL('manifest.json', function(url) {
console.log(url);
});

Conclusion

Introduction

In our previous article, we discussed the causes and solutions to the "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error when migrating a Google Chrome extension from Manifest 2 to 3. In this article, we will provide a Q&A section to help you better understand the issue and resolve it.

Q&A

Q: What is the "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error?

A: The "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error occurs when the browser tries to access a property of an object that is undefined. In the context of Chrome extensions, this error is often caused by the way the extension interacts with the browser's storage API.

Q: Why do I get this error when migrating my extension from Manifest 2 to 3?

A: There are several reasons why you might encounter this error when migrating your extension from Manifest 2 to 3. Some of the common causes include:

Incorrect usage of chrome.storage API: The chrome.storage API has undergone significant changes in Manifest V3. If you are using the API incorrectly, you might encounter this error.
Missing or incorrect permissions: In Manifest V3, you need to specify the permissions required by your extension in the manifest file. If you have missed or incorrectly specified the permissions, you might encounter this error.
Incompatible extension code: If your extension code is not compatible with Manifest V3, you might encounter this error.

Q: How do I resolve the "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error?

A: To resolve the "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error, you need to identify and fix the underlying cause. Here are some solutions to get you started:

Check the chrome.storage API usage: Make sure you are using the chrome.storage.local or chrome.storage.sync API correctly.
Specify the correct permissions: Make sure you have included the storage permission in the manifest file.
Update the extension code: Make sure your extension code is compatible with Manifest V3.

Q: What are some common mistakes that can cause this error?

A: Some common mistakes that can cause this error include:

Using the wrong API: Using the chrome.storage API instead of chrome.storage.local or chrome.storage.sync.
Missing or incorrect permissions: Missing or incorrectly specifying the storage permission in the manifest file.
Incompatible extension code: Using extension code that is not compatible with Manifest V3.

Q: How can I prevent this error from occurring in the future?

A: To prevent this error from occurring in the future, make sure to:

Use the correct API: Use the chrome.storage.local or chrome.storage.sync API correctly.
Specify the correct permissions: Include the storage permission in the manifest file.
Update the extension code: Make sure your extension code is compatible with Manifest V3.

Example Use Cases

Here are some example use cases that demonstrate how to resolve the "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error:

Example 1: Using the chrome.storage API

chrome.storage.local.get('key', function(result) {
  console.log(result);
});

Example 2: Specifying the correct permissions

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "permissions": ["storage"]
}

Example 3: Updating the extension code

// Use the new chrome.storage API
chrome.storage.local.get('key', function(result) {
  console.log(result);
});
// Use the new chrome.tabs API
chrome.tabs.query( active true, currentWindow: true , function(tabs) {
console.log(tabs);
});
// Use the new chrome.runtime API
chrome.runtime.getURL('manifest.json', function(url) {
console.log(url);
});

Conclusion

The "Uncaught TypeError: Cannot read properties of undefined (reading 'local')" error is a common issue that developers face when migrating their Google Chrome extension from Manifest 2 to 3. By understanding the causes and solutions to this error, you can resolve it and ensure that your extension works seamlessly with the browser. Remember to check the chrome.storage API usage, specify the correct permissions, and update the extension code to use the new APIs and features. With these tips and examples, you can create a high-quality extension that provides value to your users.