Migration Guides

Audience: Users upgrading from previous versions of ActingWeb.

This section provides guides for migrating between ActingWeb versions and avoiding common pitfalls.

Warning

Every guide in this section shows the API as it was during that migration, not necessarily the current API. Code blocks here must not be copied into new code without checking against Guides or Hooks Reference.

Contents

• Migrating to ActingWeb 3.15
  • Start here
  • The trust list omits credentials
  • MCP refresh tokens are single-use
  • The refresh-token grace period and SPA refresh tokens
  • Reconnect public-client connectors registered before 3.15
  • Custom authorize templates keep the PKCE inputs
  • The token endpoint’s errors
  • Token-store faults and Attributes.loaded
  • MCP client information
  • Logging
  • Custom database backends
  • PostgreSQL: consumed token rows
• Migrating to ActingWeb 3.14
  • Start here
  • Look up items by value, not position
  • Breaking changes
  • A permission gap in property lists is fixed
  • Two notification (subscription) fixes
  • Retrying a failed list update is safer, in one specific case
  • New, opt-in: faster reads that can be a moment out of date
  • New: a tool to find orphaned data
  • Faster out of the box
• Migrating to ActingWeb 3.13
  • Start here
  • Property lists: storage format, repair, and fail-fast reads
  • Migration refuses damaged lists
  • MCP: structuredContent is now opt-in
  • Security: MCP trust-cache authorization bypass
  • DynamoDB scalability: reverse lookup, capacity, and table management
• Migrating to ActingWeb 3.11
  • Overview
  • Who Needs to Migrate?
  • Required: Database
  • Breaking Changes
  • Behavioral Changes to Verify
  • Dependencies
  • New Optional Features (no action required)
  • Backward Compatibility
• Migrating to ActingWeb 3.10
  • Overview
  • Who Needs to Migrate?
  • New Components
  • Migration Guide
  • Configuration Reference
  • Testing Your Migration
  • Backward Compatibility
  • Troubleshooting
  • Breaking Change: Bucket Naming Convention
  • Peer Permissions Caching
  • Multi-Provider OAuth Support
  • See Also
• Migrating to ActingWeb 3.7
  • Overview
  • Who Needs to Migrate?
  • Breaking Changes
  • Migration Guide
  • Architecture Changes
  • Testing Your Migration
  • Benefits of Upgrading
  • Backward Compatibility
  • Summary
• ActingWeb v3.1 Migration Guide
• Overview of Changes
• Migration Steps
  • Step 1: Replace OnAWBase Class
  • Step 2: Update Handler Instantiation
  • Step 3: Update Flask Integration
• Hook Type Mapping
  • OnAWBase Method Mapping
• Hook Function Signatures
  • Property Hooks
  • Callback Hooks
  • Application-Level Callback Hooks
  • Method Hooks
  • Action Hooks
  • Lifecycle Hooks
  • Subscription Hooks
• Benefits of Migration
• Common Migration Issues
  • Type Errors
  • Missing Imports
  • Handler Parameters
• Need Help?
• Common Pitfalls
  • Actor vs ActorInterface
  • Hooks: returning None
  • Properties vs Property Lists
  • Looping over list items by index is slow
  • Base paths in templates
  • OAuth providers
  • DynamoDB local vs AWS
  • Devtest endpoints

Version Migrations

v3.15 Migration

Guide for upgrading to ActingWeb 3.15, a security release for the MCP OAuth2 server and the trust API. The trust list stops returning peer secrets, MCP refresh tokens become single-use, public MCP clients (such as Codex) work, and PKCE is enforced on the built-in sign-in pages. Connectors added before 3.15 that refresh without their issued secret (Codex) need to be removed and added again once. The refresh-token grace period becomes a setting (default unchanged), and the SPA guide gains how native clients avoid being signed out when a refresh response is lost to sleep.

v3.14 Migration

Guide for upgrading to ActingWeb 3.14. Property lists are faster and cheaper to work with, especially for code that looks up items by position in a loop — the guide shows the new, faster way (find(), remove_where(), update_where()). Three small breaking changes, a fix for a permission gap that let read-only peers write to property lists, and a new command-line tool for finding leftover data from deleted actors (actingweb-verify-orphans).

v3.13 Migration

Guide for upgrading to ActingWeb 3.13. It covers four largely independent pieces of work — the DynamoDB scalability change and its required reverse-lookup backfill, an MCP trust-cache authorization fix, the MCP structuredContent behaviour change, and the property-list storage format — and opens with a “Start here” section that says which of them apply depending on whether you are coming from 3.12.x or from one of the 3.13 release candidates. If you use list properties, do the sweep in step 1 before upgrading — list reads now fail loudly on pre-existing data damage that earlier releases silently skipped past, so sweeping and repairing comes first.

v3.11 Migration

Guide for upgrading to ActingWeb 3.11, covering the one new PostgreSQL migration (chain_id index), DynamoDB TTL for token cleanup, SPA/mobile refresh-token rotation hardening, the SPA OAuth redirect_uri allowlist, the removal of the optional MCP SDK objects, and the new Apple/GitHub/Google-native sign-in providers.

v3.10 Migration

Guide for upgrading to ActingWeb 3.10, covering automatic subscription processing with CallbackProcessor, RemotePeerStore, FanOutManager, and peer capabilities.

v3.7 Migration

Guide for upgrading to ActingWeb 3.7, covering developer API extensions for SubscriptionManager and TrustManager with cleaner APIs and automatic lifecycle hooks.

v3.1 Migration

Guide for upgrading to ActingWeb 3.1, including changes to the developer API, unified access control, and handler architecture.

Common Issues

Common Pitfalls

Frequently encountered issues and their solutions when working with ActingWeb.

Migration Checklist

When upgrading ActingWeb:

1. Read the relevant migration guide

2. Review breaking changes

3. Update your configuration

4. Test in development environment

5. Run your test suite

6. Deploy with monitoring

See Also

• Configuration Reference - Configuration reference

• Troubleshooting - Troubleshooting guide

• CHANGELOG - Full changelog