diff --git a/docs/generated/changelog.html b/docs/generated/changelog.html
index 3082cfcf9..6d974f42c 100644
--- a/docs/generated/changelog.html
+++ b/docs/generated/changelog.html
@@ -12,7 +12,9 @@ <h1>Agent-JS Changelog</h1>
     <section>
       <h2>Version x.x.x</h2>
       <ul>
-        <li></li>
+        <li>
+          Adds more helpful error message for when principal is undefined during actor creation
+        </li>
       </ul>
       <h2>Version 0.19.2</h2>
       <ul>
diff --git a/packages/agent/src/actor.test.ts b/packages/agent/src/actor.test.ts
index bf1824d21..b1f56fffa 100644
--- a/packages/agent/src/actor.test.ts
+++ b/packages/agent/src/actor.test.ts
@@ -6,6 +6,7 @@ import { CallRequest, SubmitRequestType, UnSigned } from './agent/http/types';
 import * as cbor from './cbor';
 import { requestIdOf } from './request_id';
 import * as pollingImport from './polling';
+import { ActorConfig } from './actor';
 
 const importActor = async (mockUpdatePolling?: () => void) => {
   jest.dontMock('./polling');
@@ -325,6 +326,19 @@ describe('makeActor', () => {
       );
     }
   });
+  it('should throw a helpful error if the canisterId is not set', async () => {
+    const httpAgent = new HttpAgent({ host: 'http://localhost' });
+    const actorInterface = () => {
+      return IDL.Service({
+        greet: IDL.Func([IDL.Text], [IDL.Text]),
+      });
+    };
+    const { Actor } = await importActor();
+    const config = { agent: httpAgent } as any as ActorConfig;
+    expect(() => Actor.createActor(actorInterface, config)).toThrowError(
+      'Canister ID is required, but recieved undefined instead. If you are using automatically generated declarations, this may be because your application is not setting the canister ID in process.env correctly.',
+    );
+  });
 });
 
 // TODO: tests for rejected, unknown time out
diff --git a/packages/agent/src/actor.ts b/packages/agent/src/actor.ts
index 2eb821e15..7494fd9ce 100644
--- a/packages/agent/src/actor.ts
+++ b/packages/agent/src/actor.ts
@@ -285,6 +285,10 @@ export class Actor {
       [x: string]: ActorMethod;
 
       constructor(config: ActorConfig) {
+        if (!config.canisterId)
+          throw new AgentError(
+            `Canister ID is required, but recieved ${typeof config.canisterId} instead. If you are using automatically generated declarations, this may be because your application is not setting the canister ID in process.env correctly.`,
+          );
         const canisterId =
           typeof config.canisterId === 'string'
             ? Principal.fromText(config.canisterId)
@@ -316,6 +320,11 @@ export class Actor {
     interfaceFactory: IDL.InterfaceFactory,
     configuration: ActorConfig,
   ): ActorSubclass<T> {
+    if (!configuration.canisterId) {
+      throw new AgentError(
+        `Canister ID is required, but recieved ${typeof configuration.canisterId} instead. If you are using automatically generated declarations, this may be because your application is not setting the canister ID in process.env correctly.`,
+      );
+    }
     return new (this.createActorClass(interfaceFactory))(
       configuration,
     ) as unknown as ActorSubclass<T>;