[$250] Something went wrong error appears when clear cache after create agent rule

[applause-bot]

If you haven’t already, check out our contributing guidelines for onboarding and email contributors@expensify.com to request to join our Slack channel!

---

Version Number: 9.4.41-0
Reproducible in staging?: Yes
Reproducible in production?: Yes
If this was caught during regression testing, add the test name, ID and link from BrowserStack: #95875
Email or phone of affected tester (no customers): gocemate+buzz1779@gmail.com
Issue reported by: Applause Internal Team
Bug source: Pull Request QA execution
Device used: windows 10/chrome
App Component: Other

Action Performed:

1. Open workspaces tab and choose a workspace
2. Open Rules page and press "Add agent rule" in Agent rules section
3. Select any suggested rule and press Next
4. Turn on "Force offline" and press "Add agent rule" again
5. Select a suggestion and press Next to go to edit page, make any changes and press Save.
6. On Rules page verify the new rules is available as gray under "Agent rules"
7. Open Account tab > Troubleshoot and turn off "Force offline" and clear cache by pressing "Clear cache and restart"
8. Go back to Rules

Expected Result:

There should be no error message under the created Agent rules

Actual Result:

There is an error "Oops... something went wrong and your request could not be completed. Please try again later.
Auth AddPolicyAgentRule returned an error" under the created Agent rule

Workaround:

Unknown

Platforms:

• Android: App
• Android: mWeb Chrome
• iOS: App
• iOS: mWeb Safari
• iOS: mWeb Chrome
• Windows: Chrome
• MacOS: Chrome Safari

Screenshots/Videos

Bug7213153_1784609099596.Recording__1221.mp4

View all open jobs on GitHub

Applause Internal Information
Exported by: Julia Ponikarchuk
Bug ID: 7213153

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022079461829858147067
• Upwork Job ID: 2079461829858147067
• Last Price Increase: 2026-07-21

[applause-bot]

While Applause doesn't embed attachments for this bug, here are the links for quick view:
https://platform.applause.com/services/links/v1/external/f3465fcd155da01b283acee53a35d39a733265de3f2dad2a5c6593fd2abdbb4d

[MelvinBot]

Proposal

⚠️ Confidence: Medium. The App-side mechanics below are confirmed in code. The visible error string ("Auth AddPolicyAgentRule returned an error") is returned by the backend, and I could not query logs in this run to confirm exactly why the server rejects the replayed request.

What is the root cause of that problem?

The rule is created while offline, so the AddPolicyAgentRule write is queued (not sent). Then "Clear cache and restart" wipes the optimistic Onyx data but deliberately preserves and replays the queued request, and when that replayed request reaches the server it returns an error, which is written back onto the rule as the red error you see.

Two App-side factors combine here:

1. Clear cache replays the queued write. clearOnyxAndResetApp snapshots the in-memory request queue before clearing, wipes all Onyx keys not in KEYS_TO_PRESERVE (the optimistic agent rule is wiped; the on-disk queue keys are wiped too), then re-enqueues the snapshotted requests after OpenApp resolves. So the queued AddPolicyAgentRule survives and fires.

2. Create-then-edit offline produces two conflicting requests for the same rule. The agentRuleID is client-generated with rand64() at AddAgentRulePage.tsx:155. Editing the still-pending rule fires a separate UpdatePolicyAgentRule for that same ID (EditAgentRulePage.tsx:75-81). Neither addPolicyAgentRule nor updatePolicyAgentRule pass any offline conflict-resolution config (getConflictingRequests), so the two are not collapsed — they replay as ADD then UPDATE for the same ID.

The server ultimately returns the error. Because the error message is generated backend-side, the definitive rejection reason (e.g. "rule already exists", a duplicate replay of the same ADD, or the trailing UPDATE racing the ADD) cannot be confirmed from the App code alone and needs Auth logs.

What changes do you think we should make in order to solve the problem?

The most likely App-side fix is to add offline conflict resolution to the agent-rule write actions so a rule created-then-edited offline collapses into a single request instead of replaying ADD + UPDATE separately:

• Give updatePolicyAgentRule an apiCommandConfig with getConflictingRequests that, when a pending ADD_POLICY_AGENT_RULE for the same agentRuleID exists, merges the new prompt into that queued ADD (so only one create with the final prompt is sent).
• Apply the same pattern to deletePolicyAgentRule (an offline create-then-delete should cancel the queued ADD entirely).

This mirrors the standard optimistic/offline pattern used elsewhere in App.

However, since the error itself is returned by the server: if a single, clean replayed AddPolicyAgentRule still fails after this change, the root cause is backend-side and outside this repo — that portion needs an internal engineer with Auth access to review why AddPolicyAgentRule rejects a replayed client-generated agentRuleID (idempotency / duplicate handling), ideally with logs for the affected request.

What alternative solutions did you explore? (Optional)

• Preserving the optimistic Onyx data across clear-cache so the failure at least renders against a consistent rule — but this treats the symptom, not the duplicate/conflicting-request root cause.

Investigation details & evidence

• Clear cache flow: App.ts:900-954 — snapshots queue via getAll() (line 904), clears, then re-save()s each request after openApp() (lines 941-949). PERSISTED_REQUESTS/PERSISTED_ONGOING_REQUESTS are not in KEYS_TO_PRESERVE (lines 142-168).
• addPolicyAgentRule failure data sets errors: genericErrorMessage on the rule (Rules.ts:454-469); API.write calls have no 4th apiCommandConfig arg (Rules.ts:478 and :547).
• The edit only fires UPDATE when the prompt actually changed (EditAgentRulePage.tsx:75-81) — consistent with the repro's "make any changes" step being required.
• Unconfirmed (needs logs): whether the ADD was also sent once when Force offline was toggled off just before the restart, causing a duplicate replay; and the exact server rejection reason.

---

Next Steps for Contributor+ team:
To accept: @MelvinBot implement [this](https://github.com/Expensify/App/issues/96588) to create a draft PR.
To refine: @MelvinBot <your feedback>
To reject: Explain why you are rejecting Melvin's proposal.

[abbasifaizan70]

Proposal

Please re-state the problem that we are trying to solve in this issue.

After creating an "Agent rule" while offline (so the AddPolicyAgentRule write is queued), turning "Force offline" back off and then pressing "Clear cache and restart" causes the newly-created Agent rule to show a permanent RBR error — "Oops... Auth AddPolicyAgentRule returned an error" — even though the rule was actually created successfully.

What is the root cause of that problem?

addPolicyAgentRule queues ADD_POLICY_AGENT_RULE through the normal optimistic/success/failure Onyx pattern:

App/src/libs/actions/Policy/Rules.ts

Lines 411 to 479 in f1e82a3

	function addPolicyAgentRule(policyID: string, agentRuleID: string, prompt: string) {
	if (!policyID || !agentRuleID || !prompt) {
	Log.warn('Invalid params for addPolicyAgentRule', {policyID, agentRuleID, prompt});
	return;
	}
	const policyKey = `${ONYXKEYS.COLLECTION.POLICY}${policyID}` as const;
	const onyxData: OnyxData<typeof ONYXKEYS.COLLECTION.POLICY> = {
	optimisticData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	ruleID: agentRuleID,
	created: new Date().toISOString(),
	prompt,
	pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	},
	},
	},
	},
	},
	],
	successData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	pendingAction: null,
	errors: null,
	},
	},
	},
	},
	},
	],
	failureData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	errors: ErrorUtils.getMicroSecondOnyxErrorWithTranslationKey('common.genericErrorMessage'),
	},
	},
	},
	},
	},
	],
	};
	const parameters: AddPolicyAgentRuleParams = {
	policyID,
	agentRuleID,
	prompt,
	};
	API.write(WRITE_COMMANDS.ADD_POLICY_AGENT_RULE, parameters, onyxData);
	}

While offline this request just sits in the persisted queue. Turning "Force offline" off makes SequentialQueue start sending it immediately. If the user then presses "Clear cache and restart" before that request finishes, clearOnyxAndResetApp runs: it rolls the in-flight ("ongoing") request back into the persisted queue and, after the fresh openApp() call resolves, unconditionally re-saves/resends every request from that snapshot — including the one that was just rolled back and may have already reached (or is still reaching) the server:

App/src/libs/actions/App.ts

Lines 900 to 950 in f1e82a3

	function clearOnyxAndResetApp(shouldNavigateToHomepage?: boolean) {
	// The value of isUsingImportedState will be lost once Onyx is cleared, so we need to store it
	const isStateImported = isUsingImportedState;
	rollbackOngoingRequest();
	const sequentialQueue = getAll();
	Navigation.clearPreloadedRoutes();
	// Seed LAST_FULL_RECONNECT_TIME so subscribeToFullReconnect doesn't fire a duplicate
	// ReconnectApp once the openApp() below lands NVP_RECONNECT_APP_IF_FULL_RECONNECT_BEFORE.
	const resetPromise = clearWorkboxRecoveryCaches().then(() =>
	clearOnyxAndSeedFullReconnect(KEYS_TO_PRESERVE)
	.then(() => {
	// Network key is preserved, so when exiting imported state, we should:
	// 1. Stop forcing offline mode so the app can reconnect
	// 2. Clear the IS_USING_IMPORTED_STATE flag
	// 3. Restore the original user session
	if (isStateImported) {
	setShouldForceOffline(false);
	Onyx.set(ONYXKEYS.IS_USING_IMPORTED_STATE, false);
	Log.info('[ImportedState] Exiting imported state mode, restoring original session');
	}
	if (shouldNavigateToHomepage) {
	Navigation.navigate(ROUTES.HOME);
	}
	if (preservedUserSession) {
	Onyx.set(ONYXKEYS.SESSION, preservedUserSession);
	Onyx.set(ONYXKEYS.PRESERVED_USER_SESSION, null);
	}
	if (preservedAccount) {
	Onyx.set(ONYXKEYS.ACCOUNT, preservedAccount);
	Onyx.set(ONYXKEYS.PRESERVED_ACCOUNT, null);
	}
	})
	.then(() => {
	// Requests in a sequential queue should be called even if the Onyx state is reset, so we do not lose any pending data.
	// However, the OpenApp request must be called before any other request in a queue to ensure data consistency.
	// To do that, sequential queue is cleared together with other keys, and then it's restored once the OpenApp request is resolved.
	// When exiting imported state, force openApp to run even though the variable might not be updated yet
	openApp(false, undefined, isStateImported).then(() => {
	if (!sequentialQueue || isStateImported) {
	return;
	}
	for (const request of sequentialQueue) {
	save(request);
	}
	});
	}),

rollbackOngoingRequest is what marks that request isRollback: true before it's replayed — it doesn't cancel the original in-flight call, it just guarantees the write isn't lost:

App/src/libs/actions/PersistedRequests.ts

Lines 479 to 503 in f1e82a3

	function rollbackOngoingRequest() {
	Log.info('[PersistedRequests] rollbackOngoingRequest called', false, {
	hasOngoingRequest: !!ongoingRequest,
	ongoingCommand: ongoingRequest?.command ?? 'null',
	currentQueueLength: persistedRequests.length,
	});
	if (!ongoingRequest) {
	Log.info('[PersistedRequests] No ongoingRequest to rollback');
	return;
	}
	const requestToRollback = {...ongoingRequest, isRollback: true};
	Log.info('[PersistedRequests] Rolling back request to front of queue', false, {
	command: ongoingRequest.command,
	wasMarkedAsRollback: true,
	});
	// Prepend ongoingRequest to persistedRequests
	persistedRequests.unshift(requestToRollback);
	// Clear the ongoingRequest
	ongoingRequest = null;

This means a rolled-back write is expected to sometimes hit the server twice for the same agentRuleID. The app already has infrastructure to treat that as a harmless no-op instead of a real failure — SequentialQueue's catch handler no-ops on DUPLICATE_RECORD/ALREADY_CREATED instead of applying failureData:

App/src/libs/Network/SequentialQueue.ts

Lines 220 to 261 in f1e82a3

	.catch((error: RequestError) => {
	Log.info('[SequentialQueue] Request failed with error', false, {
	command: requestToProcess.command,
	errorName: error.name ?? 'unknown',
	errorMessage: error.message ?? 'unknown',
	errorStatus: error.status ?? 'unknown',
	shouldFailAllRequests,
	});
	// On sign out we cancel any in flight requests from the user. Since that user is no longer signed in their requests should not be retried.
	// Duplicate records don't need to be retried as they just mean the record already exists on the server
	if (error.name === CONST.ERROR.REQUEST_CANCELLED || error.message === CONST.ERROR.DUPLICATE_RECORD || shouldFailAllRequests) {
	if (shouldFailAllRequests) {
	const onyxUpdates = [...(requestToProcess.failureData ?? []), ...(requestToProcess.finallyData ?? [])] as AnyOnyxUpdate[];
	Log.info('[SequentialQueue] Applying failure and finally data because shouldFailAllRequests', false, {
	command: requestToProcess.command,
	updatesCount: onyxUpdates.length,
	});
	Onyx.update(onyxUpdates);
	}
	Log.info("[SequentialQueue] Removing persisted request because it failed and doesn't need to be retried.", false, {
	command: requestToProcess.command,
	errorName: error.name,
	errorMessage: error.message,
	});
	endPersistedRequestAndRemoveFromQueue(requestToProcess);
	sequentialQueueRequestThrottle.clear();
	return process();
	}
	if (error.message === CONST.ERROR.ALREADY_CREATED) {
	const onyxUpdates = [...(requestToProcess.successData ?? []), ...(requestToProcess.finallyData ?? [])] as AnyOnyxUpdate[];
	Log.info('[SequentialQueue] Applying success and finally data on ALREADY_CREATED — resource already exists server-side', false, {
	command: requestToProcess.command,
	updatesCount: onyxUpdates.length,
	});
	Onyx.update(onyxUpdates);
	Log.info('[SequentialQueue] Removing persisted request because the resource was already created server-side.', false, {
	command: requestToProcess.command,
	errorMessage: error.message,
	});
	endPersistedRequestAndRemoveFromQueue(requestToProcess);

…but that classification only fires for two specific server response shapes handled in HttpUtils.ts: the generic MySQL "Unique Constraints Violation", or a message present in the ALREADY_CREATED_MESSAGES allowlist (today this only contains the transaction-specific message, and the comment explicitly says to add more commands as they're discovered):

App/src/libs/HttpUtils.ts

Lines 56 to 60 in f1e82a3

	/**
	* Per-command server response messages we recognize as the PHP-wrapped "AlreadyCreated" error.
	* Add new variants here as we discover them for other non-idempotent commands.
	*/
	const ALREADY_CREATED_MESSAGES = new Set<string>([CONST.ERROR_TITLE.ALREADY_CREATED_TRANSACTION]);

App/src/libs/HttpUtils.ts

Lines 148 to 166 in f1e82a3

	.then((response) => {
	// Some retried requests will result in a "Unique Constraints Violation" error from the server, which just means the record already exists
	if (response.jsonCode === CONST.JSON_CODE.BAD_REQUEST && response.message === CONST.ERROR_TITLE.DUPLICATE_RECORD) {
	throw new HttpsError({
	message: CONST.ERROR.DUPLICATE_RECORD,
	status: CONST.JSON_CODE.BAD_REQUEST.toString(),
	title: CONST.ERROR_TITLE.DUPLICATE_RECORD,
	requestID: response.requestID,
	});
	}
	// Per-command messages indicating the resource already exists on the server (e.g. retry after a successful first attempt).
	if (response.jsonCode === CONST.JSON_CODE.EXP_ERROR && response.message && ALREADY_CREATED_MESSAGES.has(response.message)) {
	throw new HttpsError({
	message: CONST.ERROR.ALREADY_CREATED,
	status: CONST.JSON_CODE.EXP_ERROR.toString(),
	title: response.message,
	});
	}

Since AddPolicyAgentRule isn't backed by the same raw unique-DB-constraint error shape and its own "already exists" message (if any) isn't registered in ALREADY_CREATED_MESSAGES, the retry that clearOnyxAndResetApp triggers surfaces to the user as a hard, generic failure instead of being silently absorbed — even though the rule already exists.

What changes do you think we should make in order to solve the problem?

This is the same class of bug the ALREADY_CREATED_MESSAGES mechanism was built for, so the fix should follow that existing pattern rather than touching the generic retry/rollback plumbing in clearOnyxAndResetApp/SequentialQueue (that plumbing is shared by every write command and is working as designed).

1. On the Auth side, AddPolicyAgentRule should detect that an agent rule with the given policyID/agentRuleID already exists and respond with a stable "already created" EXP_ERROR message (the same convention used for ALREADY_CREATED_TRANSACTION), instead of a generic error.
2. On the App side, register that new message in the ALREADY_CREATED_MESSAGES set in src/libs/HttpUtils.ts#L60 so the retried/duplicate AddPolicyAgentRule submission is treated as already-succeeded:

const ALREADY_CREATED_MESSAGES = new Set<string>([CONST.ERROR_TITLE.ALREADY_CREATED_TRANSACTION, CONST.ERROR_TITLE.ALREADY_CREATED_AGENT_RULE]);

with the corresponding constant added next to ALREADY_CREATED_TRANSACTION in src/CONST/index.ts's ERROR_TITLE object (matching the exact string Auth is updated to return), e.g.:

ALREADY_CREATED_AGENT_RULE: 'Agent rule already created.',

With this in place, when clearOnyxAndResetApp legitimately resends an already-processed AddPolicyAgentRule request, HttpUtils.ts#L160-L166 converts the response into CONST.ERROR.ALREADY_CREATED, and SequentialQueue.ts#L250-L261 applies successData/finallyData and removes the request from the queue instead of applying failureData — so the Agent rule stops showing the false "Auth AddPolicyAgentRule returned an error" RBR message after "Clear cache and restart".

[yusufdeveloper2903]

Proposal

What is the root cause of that problem?

When a user creates an agent rule while offline and then clears the app cache, the POLICY collection (containing the pending rule with pendingAction: ADD) is cleared from Onyx because it is not included in the KEYS_TO_PRESERVE_SUPPORTAL list. This creates a critical mismatch:

The causal chain:

1. User creates an agent rule while offline → addPolicyAgentRule() writes optimistic data to policy.rules.agentRules[ruleID] with pendingAction: ADD and queues an AddPolicyAgentRule API call to PersistedRequests
2. User clears cache from Account > Troubleshoot → cleanupSession() is called, which invokes clearOnyxAndSeedFullReconnect(KEYS_TO_PRESERVE_SUPPORTAL) at line 481
3. The bug: KEYS_TO_PRESERVE_SUPPORTAL on lines 330-353 does NOT include ONYXKEYS.COLLECTION.POLICY, so all policies are wiped from Onyx, along with their pending rules. The queued API call in PersistedRequests (also stored in Onyx) is also cleared
4. App restarts, openPolicyRulesPage() fetches rules from the server, which has no trace of the rule (the API call was never sent)
5. The error appears: If the AddPolicyAgentRule API call somehow completes or retries after cache clear (from a browser tab that held it, or from request replay), it fails. The failureData in addPolicyAgentRule() at lines 375-390 attempts to merge an error onto policy.rules.agentRules[ruleID], but since the entire policy structure was cleared from Onyx, Onyx creates or updates an orphaned error state. This results in the error message: "Oops... something went wrong and your request could not be completed. Please try again later. Auth AddPolicyAgentRule returned an error"

The root cause is the cache-clear behavior not accounting for pending rule operations. Policies should survive cache clear so that pending API calls and their Onyx state remain consistent.

Evidence from code:

App/src/libs/actions/Session/index.ts

Lines 330 to 353 in fd467ee

	const KEYS_TO_PRESERVE_SUPPORTAL = [
	ONYXKEYS.NVP_TRY_FOCUS_MODE,
	ONYXKEYS.PREFERRED_THEME,
	ONYXKEYS.NVP_PREFERRED_LOCALE,
	ONYXKEYS.RAM_ONLY_ARE_TRANSLATIONS_LOADING,
	ONYXKEYS.SESSION,
	ONYXKEYS.STASHED_SESSION,
	ONYXKEYS.HAS_LOADED_APP,
	ONYXKEYS.STASHED_CREDENTIALS,
	ONYXKEYS.HYBRID_APP,
	// We need to preserve the sidebar loaded state since we never unmount the sidebar when connecting as a delegate
	// This allows the report screen to load correctly when the delegate token expires and the delegate is returned to their original account.
	ONYXKEYS.RAM_ONLY_IS_SIDEBAR_LOADED,
	ONYXKEYS.NETWORK,
	ONYXKEYS.SHOULD_USE_STAGING_SERVER,
	ONYXKEYS.IS_DEBUG_MODE_ENABLED,
	// Preserve IS_USING_IMPORTED_STATE so that when transitioning to/from supportal,
	// we know if we're in imported state mode and should skip API calls that would cause infinite loading
	ONYXKEYS.IS_USING_IMPORTED_STATE,
	ONYXKEYS.COLLECTION.PASSKEY_CREDENTIALS,
	ONYXKEYS.COLLECTION.DEVICE_BIOMETRICS,
	];

Line 335 preserves ONYXKEYS.SESSION, but line 330-353 shows ONYXKEYS.COLLECTION.POLICY is absent.

App/src/libs/actions/Policy/Rules.ts

Lines 332 to 400 in fd467ee

	function addPolicyAgentRule(policyID: string, agentRuleID: string, prompt: string) {
	if (!policyID || !agentRuleID || !prompt) {
	Log.warn('Invalid params for addPolicyAgentRule', {policyID, agentRuleID, prompt});
	return;
	}
	const policyKey = `${ONYXKEYS.COLLECTION.POLICY}${policyID}` as const;
	const onyxData: OnyxData<typeof ONYXKEYS.COLLECTION.POLICY> = {
	optimisticData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	ruleID: agentRuleID,
	created: new Date().toISOString(),
	prompt,
	pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	},
	},
	},
	},
	},
	],
	successData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	pendingAction: null,
	errors: null,
	},
	},
	},
	},
	},
	],
	failureData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	errors: ErrorUtils.getMicroSecondOnyxErrorWithTranslationKey('common.genericErrorMessage'),
	},
	},
	},
	},
	},
	],
	};
	const parameters: AddPolicyAgentRuleParams = {
	policyID,
	agentRuleID,
	prompt,
	};
	API.write(WRITE_COMMANDS.ADD_POLICY_AGENT_RULE, parameters, onyxData);
	}

The addPolicyAgentRule() function creates optimistic Onyx data at policy.rules.agentRules[agentRuleID] and on failure (lines 375-390) merges an error onto the same path. If that policy key is cleared from Onyx before the error merge occurs, the state becomes inconsistent.

What changes do you think we should make in order to solve the problem?

Add ONYXKEYS.COLLECTION.POLICY to the KEYS_TO_PRESERVE_SUPPORTAL list in src/libs/actions/Session/index.ts. This ensures that policies with pending rules survive cache clear, keeping the local state consistent with queued API calls.

Why this is safe:

• SESSION is already preserved (line 335), so auth state survives cache clear
• Policies are app-critical data and should not be lost during cache clear (cache clear is primarily a debugging/recovery tool for non-essential cache)
• The preserve list already includes device biometrics and passkeys (lines 351-352), which are also sensitive persisted state — policies are similarly important
• Preserving policies ensures offline-created rules are not silently dropped; users see pending states and can explicitly delete unwanted rules
• After reconnection, openPolicyRulesPage() will fetch fresh policy data from the server and merge it with the preserved local state, ensuring consistency

Result: Users who create agent rules offline and then clear cache will see the pending rule survive the clear, maintaining the optimistic UI state. When the app reconnects, the pending API call (if preserved in PersistedRequests) will sync correctly, or the server response will correct the state. The error will not appear because the Onyx structure matches the API operation's expected state.

What alternative solutions did you explore? (Optional)

• Exclude pending policies from cache clear, not all policies: Filter out policies with pending rules before clearing. This is more surgical but complex to implement and requires tracking pending operations across multiple rule types (agent, coding, etc.).
• Retry the API call on cache clear instead of clearing it: When cache is cleared, re-send pending API calls instead of dropping them. This risks duplicate API calls and doesn't resolve the state mismatch if the user was offline when cache clear happened.
• Clear PersistedRequests separately from Onyx: Leave policies in Onyx but clear PersistedRequests to drop pending API calls. This would prevent errors but lose the rule's existence entirely, confusing users who created it.

[dilshodmackbook-sketch]

🚨 Edited by proposal-police: This proposal was edited at 2026-07-21 07:06:34 UTC.

Proposal

Please re-state the problem that we are trying to solve in this issue.

An agent rule that is created while offline shows a red "Auth AddPolicyAgentRule returned an error" error after the user turns off Force offline and runs Clear cache and restart, even though the rule itself was created successfully on the server (its prompt text still renders).

What is the root cause of that problem?

The error is stamped by the failure handler of addPolicyAgentRule, which fires because the AddPolicyAgentRule request is sent to Auth twice for the same rule.

When you create an agent rule offline, addPolicyAgentRule queues the write with a client-generated agentRuleID and this failure update:

App/src/libs/actions/Policy/Rules.ts

Lines 454 to 471 in f1e82a3

	failureData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	errors: ErrorUtils.getMicroSecondOnyxErrorWithTranslationKey('common.genericErrorMessage'),
	},
	},
	},
	},
	},
	],
	};

Clear cache and restart calls clearOnyxAndResetApp, which is deliberately built to not lose pending writes: it snapshots the sequential queue with getAll() before clearing Onyx, then re-saves every request after openApp resolves:

App/src/libs/actions/App.ts

Lines 936 to 948 in f1e82a3

	.then(() => {
	// Requests in a sequential queue should be called even if the Onyx state is reset, so we do not lose any pending data.
	// However, the OpenApp request must be called before any other request in a queue to ensure data consistency.
	// To do that, sequential queue is cleared together with other keys, and then it's restored once the OpenApp request is resolved.
	// When exiting imported state, force openApp to run even though the variable might not be updated yet
	openApp(false, undefined, isStateImported).then(() => {
	if (!sequentialQueue || isStateImported) {
	return;
	}
	for (const request of sequentialQueue) {
	save(request);
	}

Because the user turns Force offline off and immediately clears the cache, the just-flushed AddPolicyAgentRule request is still in that snapshot (a request that is mid-flight is also rolled back into the queue by rollbackOngoingRequest()). Auth has already applied it, so openApp refetches the policy with the new rule, and then the snapshot is replayed — sending AddPolicyAgentRule a second time for an agentRuleID that now exists. Auth rejects the duplicate, failureData runs, and the generic error is merged onto a rule that is actually present. That is exactly what the video shows: the rules render with their prompts, each carrying the error.

This only affects agent rules because AddPolicyAgentRule is a non-idempotent insert. The sibling merchant/coding rule flow uses SetPolicyCodingRule, an upsert, so replaying it is a harmless no-op and it never produces this error:

App/src/libs/actions/Policy/Rules.ts

Lines 174 to 277 in f1e82a3

	function setPolicyCodingRule(policyID: string, form: MerchantRuleForm, policy: Policy | undefined, ruleID?: string, shouldUpdateMatchingTransactions = false) {
	if (!policyID || !form.merchantToMatch) {
	Log.warn('Invalid params for setPolicyCodingRule', {policyID, merchantToMatch: form.merchantToMatch});
	return;
	}
	const isEditing = !!ruleID;
	const existingRule = isEditing ? policy?.rules?.codingRules?.[ruleID] : undefined;
	// Build rule with nulls for Onyx (to remove cleared fields) and without nulls for API
	const ruleFieldsForOnyx = mapFormFieldsToRuleForOnyx(form, policy);
	const ruleFieldsForAPI = mapFormFieldsToRuleForAPI(form, policy);
	const targetRuleID = ruleID ?? NumberUtils.rand64();
	const operator = form.matchType ?? CONST.SEARCH.SYNTAX_OPERATORS.CONTAINS;
	const created = existingRule?.created ?? new Date().toISOString();
	const pendingAction = isEditing ? CONST.RED_BRICK_ROAD_PENDING_ACTION.UPDATE : CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD;
	const ruleForOnyx = {
	ruleID: targetRuleID,
	filters: {
	left: 'merchant',
	operator,
	right: form.merchantToMatch,
	},
	...ruleFieldsForOnyx,
	created,
	pendingAction,
	};
	// Rule for API (excludes null values)
	const ruleForAPI: Partial<CodingRule> = {
	ruleID: targetRuleID,
	filters: {
	left: 'merchant',
	operator,
	right: form.merchantToMatch,
	},
	...ruleFieldsForAPI,
	created,
	};
	const policyKey = `${ONYXKEYS.COLLECTION.POLICY}${policyID}` as const;
	// On failure: for new rules, remove the optimistic rule; for edits, restore the original rule
	const failureRuleValue = isEditing ? existingRule : null;
	const onyxData = {
	optimisticData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	codingRules: {
	[targetRuleID]: ruleForOnyx,
	},
	},
	},
	},
	],
	successData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	codingRules: {
	[targetRuleID]: {
	pendingAction: null,
	errors: null,
	},
	},
	},
	},
	},
	],
	failureData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	codingRules: {
	[targetRuleID]: {
	...failureRuleValue,
	pendingAction: isEditing ? null : CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	errors: ErrorUtils.getMicroSecondOnyxErrorWithTranslationKey('common.genericErrorMessage'),
	},
	},
	},
	},
	},
	],
	};
	const parameters: SetPolicyCodingRuleParams = {
	policyID,
	codingRuleID: targetRuleID,
	codingRuleValue: JSON.stringify(ruleForAPI),
	shouldUpdateMatchingTransactions,
	};
	API.write(WRITE_COMMANDS.SET_POLICY_CODING_RULE, parameters, onyxData);

What changes do you think we should make in order to solve the problem?

Make AddPolicyAgentRule idempotent so replaying an already-applied request is a no-op instead of an error, matching the upsert behaviour of SetPolicyCodingRule.

On the Auth command for AddPolicyAgentRule, when a rule with the incoming agentRuleID already exists on the policy, return the existing rule as a success (no-op) instead of throwing "returned an error". Since the App generates agentRuleID on the client and passes it in the request params, this dedupe is a straightforward lookup:

AddPolicyAgentRuleParams = { policyID, agentRuleID, prompt }

This is the correct layer to fix it: clearOnyxAndResetApp intentionally replays the persisted queue to preserve offline work, so the same write can legitimately reach the server more than once, and the client cannot know the request already succeeded before replaying it.

What alternative solutions did you explore? (Optional)

App-only guard, if we prefer not to touch Auth: in the clearOnyxAndResetApp replay step, after openApp resolves, drop any snapshotted AddPolicyAgentRule (and UpdatePolicyAgentRule) whose agentRuleID is already present in the freshly fetched policy before calling save(request). This prevents the duplicate send without a backend change, but it is narrower and reintroduces the risk for any future non-idempotent write.

Alternatively, we could suppress/clear the error in addPolicyAgentRule's failureData when the rule already exists in Onyx, but that only hides the symptom — the redundant network request and duplicate-key rejection still happen.

[mukhrr]

🚨 Edited by proposal-police: This proposal was edited at 2026-07-21 07:39:55 UTC.

Proposal

What is the root cause of that problem?

clearOnyxAndResetApp() snapshots the sequential queue, clears Onyx, runs openApp(), and then blindly replays every request from the snapshot.

App/src/libs/actions/App.ts

Lines 900 to 949 in f1e82a3

	function clearOnyxAndResetApp(shouldNavigateToHomepage?: boolean) {
	// The value of isUsingImportedState will be lost once Onyx is cleared, so we need to store it
	const isStateImported = isUsingImportedState;
	rollbackOngoingRequest();
	const sequentialQueue = getAll();
	Navigation.clearPreloadedRoutes();
	// Seed LAST_FULL_RECONNECT_TIME so subscribeToFullReconnect doesn't fire a duplicate
	// ReconnectApp once the openApp() below lands NVP_RECONNECT_APP_IF_FULL_RECONNECT_BEFORE.
	const resetPromise = clearWorkboxRecoveryCaches().then(() =>
	clearOnyxAndSeedFullReconnect(KEYS_TO_PRESERVE)
	.then(() => {
	// Network key is preserved, so when exiting imported state, we should:
	// 1. Stop forcing offline mode so the app can reconnect
	// 2. Clear the IS_USING_IMPORTED_STATE flag
	// 3. Restore the original user session
	if (isStateImported) {
	setShouldForceOffline(false);
	Onyx.set(ONYXKEYS.IS_USING_IMPORTED_STATE, false);
	Log.info('[ImportedState] Exiting imported state mode, restoring original session');
	}
	if (shouldNavigateToHomepage) {
	Navigation.navigate(ROUTES.HOME);
	}
	if (preservedUserSession) {
	Onyx.set(ONYXKEYS.SESSION, preservedUserSession);
	Onyx.set(ONYXKEYS.PRESERVED_USER_SESSION, null);
	}
	if (preservedAccount) {
	Onyx.set(ONYXKEYS.ACCOUNT, preservedAccount);
	Onyx.set(ONYXKEYS.PRESERVED_ACCOUNT, null);
	}
	})
	.then(() => {
	// Requests in a sequential queue should be called even if the Onyx state is reset, so we do not lose any pending data.
	// However, the OpenApp request must be called before any other request in a queue to ensure data consistency.
	// To do that, sequential queue is cleared together with other keys, and then it's restored once the OpenApp request is resolved.
	// When exiting imported state, force openApp to run even though the variable might not be updated yet
	openApp(false, undefined, isStateImported).then(() => {
	if (!sequentialQueue || isStateImported) {
	return;
	}
	for (const request of sequentialQueue) {
	save(request);
	}
	});

The snapshot is taken after rollbackOngoingRequest(), which prepends the request that is currently in flight back onto the queue.

App/src/libs/actions/PersistedRequests.ts

Lines 479 to 502 in f1e82a3

	function rollbackOngoingRequest() {
	Log.info('[PersistedRequests] rollbackOngoingRequest called', false, {
	hasOngoingRequest: !!ongoingRequest,
	ongoingCommand: ongoingRequest?.command ?? 'null',
	currentQueueLength: persistedRequests.length,
	});
	if (!ongoingRequest) {
	Log.info('[PersistedRequests] No ongoingRequest to rollback');
	return;
	}
	const requestToRollback = {...ongoingRequest, isRollback: true};
	Log.info('[PersistedRequests] Rolling back request to front of queue', false, {
	command: ongoingRequest.command,
	wasMarkedAsRollback: true,
	});
	// Prepend ongoingRequest to persistedRequests
	persistedRequests.unshift(requestToRollback);
	// Clear the ongoingRequest
	ongoingRequest = null;

The key point is that an ongoing request has, by definition, already been sent to the server: SequentialQueue.process() returns early while we are offline, so nothing ever becomes ongoing until we are back online.

App/src/libs/Network/SequentialQueue.ts

Lines 152 to 155 in f1e82a3

	if (isOfflineNetwork()) {
	Log.info('[SequentialQueue] Unable to process. We are offline.');
	return Promise.resolve();
	}

That is exactly the state the repro steps create. Turning off "Force offline" flushes the queued AddPolicyAgentRule; it is still in flight (agent-rule creation is not instant) when "Clear cache and restart" is pressed. The reset rolls that in-flight request back into the snapshot, openApp() then loads the authoritative policy — which already contains the rule the server just created — and the snapshot is replayed, sending AddPolicyAgentRule a second time with the same client-generated agentRuleID.

The duplicate fails, and the request's failureData merges pendingAction: 'add' plus a generic error back onto the rule that was in fact saved correctly.

App/src/libs/actions/Policy/Rules.ts

Lines 454 to 469 in f1e82a3

	failureData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	errors: ErrorUtils.getMicroSecondOnyxErrorWithTranslationKey('common.genericErrorMessage'),
	},
	},
	},
	},
	},
	],

AgentRulesList renders those errors through OfflineWithFeedback, which is the red message in the report.

App/src/components/AgentRules/AgentRulesList.tsx

Lines 49 to 55 in f1e82a3

	<OfflineWithFeedback
	key={rule.ruleID}
	pendingAction={rule.pendingAction}
	errors={rule.errors}
	errorRowStyles={styles.agentRulesErrorRow}
	onClose={() => clearPolicyAgentRuleErrors(policyID, rule.ruleID, rule)}
	>

I confirmed this by driving the real clearOnyxAndResetApp() in a test with one in-flight request and one still queued. On main the commands re-saved after the reset are ["OpenApp", "AddPolicyAgentRule", "UpdatePolicyAgentRule"] — the already-delivered create is sent again, which is the duplicate that errors.

This is not specific to agent rules; it affects any create command whose ID is generated client-side. It only shows up here because AddPolicyAgentRule is slow enough that the user reliably reaches the Troubleshoot button while the request is still in flight.

What changes do you think we should make in order to solve the problem?

I think we should stop replaying the request that was in flight when the reset started, while still restoring everything that was only waiting in the queue.

In clearOnyxAndResetApp(), I would capture whether there is an ongoing request before rolling it back, and drop it from the snapshot when we are online. rollbackOngoingRequest() prepends it, so it is the first entry:

 const isStateImported = isUsingImportedState;
+const shouldSkipOngoingRequest = !!getOngoingRequest() && !getIsOffline();
 rollbackOngoingRequest();
-const sequentialQueue = getAll();
+const sequentialQueue = shouldSkipOngoingRequest ? getAll().slice(1) : getAll();

The reasoning is that openApp() immediately refetches the authoritative state, which already reflects whatever the in-flight request did, so replaying it can only produce a duplicate write. Everything that never left the client is still restored, so no offline work is lost. I would keep the !getIsOffline() guard so the existing behaviour — and the existing clearOnyxAndResetApp preserves rolled-back ongoing requests across reset regression test — is unchanged for the offline case, where the request genuinely never went out.

I added a regression test in tests/actions/AppTest.ts that saves one request, marks it ongoing while online, queues a second one, calls clearOnyxAndResetApp(), and asserts that only the waiting request is re-saved. It fails on main (Received array: ["OpenApp", "AddPolicyAgentRule", "UpdatePolicyAgentRule"]) and passes with the change.

What alternative solutions did you explore? (Optional)

I looked at reusing the existing "resource already exists server-side" path, which converts a duplicate response into successData instead of failureData:

App/src/libs/Network/SequentialQueue.ts

Lines 250 to 263 in f1e82a3

	if (error.message === CONST.ERROR.ALREADY_CREATED) {
	const onyxUpdates = [...(requestToProcess.successData ?? []), ...(requestToProcess.finallyData ?? [])] as AnyOnyxUpdate[];
	Log.info('[SequentialQueue] Applying success and finally data on ALREADY_CREATED — resource already exists server-side', false, {
	command: requestToProcess.command,
	updatesCount: onyxUpdates.length,
	});
	Onyx.update(onyxUpdates);
	Log.info('[SequentialQueue] Removing persisted request because the resource was already created server-side.', false, {
	command: requestToProcess.command,
	errorMessage: error.message,
	});
	endPersistedRequestAndRemoveFromQueue(requestToProcess);
	sequentialQueueRequestThrottle.clear();
	return process();

That path is driven by an allow-list of exact server messages in HttpUtils, and the response here is the generic Auth AddPolicyAgentRule returned an error, which also fires for real permission and validation failures — so whitelisting it would hide legitimate errors. It would become viable if the backend returned a distinct duplicate message for this command, but the client-side fix above is not blocked on that and covers every create command with a client-generated ID.

I also considered filtering the restored queue by checking whether each request's entity already exists in the refreshed policy, but that requires per-command knowledge in App.ts and would have to be repeated for every new create command. Suppressing the error inside addPolicyAgentRule() was rejected outright, since it would mask genuine failures.

[lorretheboy]

🚨 Edited by proposal-police: This proposal was edited at 2026-07-21 07:11:57 UTC.

Proposal

What is the root cause of that problem?

The rule is created while force-offline, so AddPolicyAgentRule sits in the persisted request queue. When force offline is turned off, the queue starts flushing and the request goes out on the wire. A moment later the user presses "Clear cache and restart", which runs clearOnyxAndResetApp. It rolls the in-flight request back into the queue and snapshots the queue:

App/src/libs/actions/App.ts

Lines 900 to 904 in f1e82a3

	function clearOnyxAndResetApp(shouldNavigateToHomepage?: boolean) {
	// The value of isUsingImportedState will be lost once Onyx is cleared, so we need to store it
	const isStateImported = isUsingImportedState;
	rollbackOngoingRequest();
	const sequentialQueue = getAll();

rollbackOngoingRequest only moves the request back in memory — it does not (and cannot) cancel the HTTP request that is already on the wire, which the server goes on to process and create the rule:

App/src/libs/actions/PersistedRequests.ts

Lines 479 to 508 in f1e82a3

	function rollbackOngoingRequest() {
	Log.info('[PersistedRequests] rollbackOngoingRequest called', false, {
	hasOngoingRequest: !!ongoingRequest,
	ongoingCommand: ongoingRequest?.command ?? 'null',
	currentQueueLength: persistedRequests.length,
	});
	if (!ongoingRequest) {
	Log.info('[PersistedRequests] No ongoingRequest to rollback');
	return;
	}
	const requestToRollback = {...ongoingRequest, isRollback: true};
	Log.info('[PersistedRequests] Rolling back request to front of queue', false, {
	command: ongoingRequest.command,
	wasMarkedAsRollback: true,
	});
	// Prepend ongoingRequest to persistedRequests
	persistedRequests.unshift(requestToRollback);
	// Clear the ongoingRequest
	ongoingRequest = null;
	Log.info('[PersistedRequests] Rollback complete', false, {
	rolledBackCommand: requestToRollback.command,
	newQueueLength: persistedRequests.length,
	ongoingRequestCleared: true,
	});

After the reset, the snapshot is re-saved and re-sent:

App/src/libs/actions/App.ts

Lines 936 to 949 in f1e82a3

	.then(() => {
	// Requests in a sequential queue should be called even if the Onyx state is reset, so we do not lose any pending data.
	// However, the OpenApp request must be called before any other request in a queue to ensure data consistency.
	// To do that, sequential queue is cleared together with other keys, and then it's restored once the OpenApp request is resolved.
	// When exiting imported state, force openApp to run even though the variable might not be updated yet
	openApp(false, undefined, isStateImported).then(() => {
	if (!sequentialQueue || isStateImported) {
	return;
	}
	for (const request of sequentialQueue) {
	save(request);
	}
	});

So AddPolicyAgentRule is sent twice with the same agentRuleID. Auth rejects the duplicate ("Auth AddPolicyAgentRule returned an error"), and the replayed request's failureData paints the error under the rule:

App/src/libs/actions/Policy/Rules.ts

Lines 454 to 469 in f1e82a3

	failureData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	errors: ErrorUtils.getMicroSecondOnyxErrorWithTranslationKey('common.genericErrorMessage'),
	},
	},
	},
	},
	},
	],

Nothing in PR #95875's diff causes this — that PR only added the Suggestions tab UI; its QA steps just happen to exercise the generic "offline write → clear cache while queue is flushing" race, which double-sends any queued write command.

What changes do you think we should make in order to solve the problem?

Fix it in clearOnyxAndResetApp: instead of rolling back a request that is already on the wire, pause the sequential queue and let the in-flight request settle before snapshotting the queue. When a request completes it removes itself from the queue via endPersistedRequestAndRemoveFromQueue, so it is no longer in the snapshot and is never re-sent:

App/src/libs/Network/SequentialQueue.ts

Lines 199 to 218 in f1e82a3

	Log.info('[SequentialQueue] Removing persisted request because it was processed successfully.', false, {
	command: requestToProcess.command,
	remainingRequests: getAllPersistedRequests().length,
	});
	endPersistedRequestAndRemoveFromQueue(requestToProcess);
	// Only commit queueFlushedData (e.g. HAS_LOADED_APP: true) on success — HttpUtils resolves (not rejects) app-level
	// failures, so committing on a failed-but-resolved OpenApp/ReconnectApp would wrongly mark the app as loaded and
	// break self-healing on the next boot.
	if (requestToProcess.queueFlushedData && response?.jsonCode === CONST.JSON_CODE.SUCCESS) {
	Log.info('[SequentialQueue] Will store queueFlushedData.', false, {
	command: requestToProcess.command,
	queueFlushedDataLength: requestToProcess.queueFlushedData.length,
	});
	saveQueueFlushedData(...requestToProcess.queueFlushedData);
	}
	sequentialQueueRequestThrottle.clear();
	Log.info('[SequentialQueue] Continuing to process next request');
	return process();

SequentialQueue already exposes exactly what we need — pause(), getCurrentRequest() and unpause():

App/src/libs/Network/SequentialQueue.ts

Lines 643 to 648 in f1e82a3

	function getCurrentRequest(): Promise<void> {
	if (currentRequestPromise === null) {
	return Promise.resolve();
	}
	return currentRequestPromise;
	}

The important detail is the ordering — openApp is itself pushed onto the sequential queue, and flush() early-returns while the queue is paused, so we must unpause after the Onyx clear (which empties the queue) and before openApp, otherwise the reset hangs. Roughly:

SequentialQueue.pause();
await SequentialQueue.getCurrentRequest(); // in-flight request completes (or is rolled back for retry) and settles
const sequentialQueue = getAll();          // snapshot now only holds requests that were never sent
// ...existing clearWorkboxRecoveryCaches() + clearOnyxAndSeedFullReconnect(KEYS_TO_PRESERVE)...
// after the clear empties the queue:
SequentialQueue.unpause();
// ...existing openApp(...).then(() => { for (const request of sequentialQueue) save(request); })...

Because pause() stops the recursive process() chain, awaiting getCurrentRequest() resolves once the single in-flight request settles: on success it removed itself from the queue (not in the snapshot, never replayed); on a retriable failure the queue's own logic rolls it back into persistedRequests, so it is still in the snapshot and replayed exactly as today; a genuine duplicate/ALREADY_CREATED response is dropped without retry. We no longer need the explicit rollbackOngoingRequest() call, since after the await there is no lingering ongoing request. This fixes the double-send for every write command, not just AddPolicyAgentRule.

The extra wait is bounded — the in-flight request either completes or the queue's retry/give-up path resolves it — which is acceptable for a "clear cache and restart" action, and it is the safe trade: we only replay work that provably did not reach the server.

What alternative solutions did you explore? (Optional)

• Keep rollbackOngoingRequest but exclude the rolled-back (already-transmitted) request from the replay snapshot by its isRollback flag, since openApp runs right after the reset and returns the server truth (the created rule) anyway. Simpler and generic, but it drops the request in the rare case where it was moved to "ongoing" yet never actually reached the server (e.g. it failed mid-flight), so waiting for the in-flight request to settle is safer.
• Reconcile after openApp by skipping replay of any queued AddPolicyAgentRule whose agentRuleID is already present in the freshly fetched policy, or making the Auth command idempotent. Both work but are narrower — the first special-cases agent rules and re-introduces the risk for the next non-idempotent write, and the second needs a backend change — whereas settling the in-flight request fixes the race generically on the client.

[samranahm]

🚨 Edited by proposal-police: This proposal was edited at 2026-07-21 07:42:53 UTC.

Proposal

What is the root cause of that problem?

When a user creates an agent rule while Force offline is on, turns Force offline off, then immediately taps Clear cache and restart, the Rules page shows a healthy-looking rule with a false red error: "Oops... something went wrong..." plus "Auth AddPolicyAgentRule returned an error". The rule was actually created successfully on the server. Creating the same rule while already online and then clearing cache does not show the error.

This is an FE double-send race in clear-cache sequencing, not a broken agent-rule action and not a backend regression. Auth is correctly rejecting a duplicate create.

1. Offline save queues one write. addPolicyAgentRule optimistically inserts the rule with pendingAction: ADD and persists AddPolicyAgentRule with a client-generated agentRuleID. The failure path is what later paints the red brick road under the row:

App/src/libs/actions/Policy/Rules.ts

Lines 411 to 478 in daa0474

	function addPolicyAgentRule(policyID: string, agentRuleID: string, prompt: string) {
	if (!policyID || !agentRuleID || !prompt) {
	Log.warn('Invalid params for addPolicyAgentRule', {policyID, agentRuleID, prompt});
	return;
	}
	const policyKey = `${ONYXKEYS.COLLECTION.POLICY}${policyID}` as const;
	const onyxData: OnyxData<typeof ONYXKEYS.COLLECTION.POLICY> = {
	optimisticData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	ruleID: agentRuleID,
	created: new Date().toISOString(),
	prompt,
	pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	},
	},
	},
	},
	},
	],
	successData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	pendingAction: null,
	errors: null,
	},
	},
	},
	},
	},
	],
	failureData: [
	{
	onyxMethod: Onyx.METHOD.MERGE,
	key: policyKey,
	value: {
	rules: {
	agentRules: {
	[agentRuleID]: {
	pendingAction: CONST.RED_BRICK_ROAD_PENDING_ACTION.ADD,
	errors: ErrorUtils.getMicroSecondOnyxErrorWithTranslationKey('common.genericErrorMessage'),
	},
	},
	},
	},
	},
	],
	};
	const parameters: AddPolicyAgentRuleParams = {
	policyID,
	agentRuleID,
	prompt,
	};
	API.write(WRITE_COMMANDS.ADD_POLICY_AGENT_RULE, parameters, onyxData);

2. Turning Force offline off starts the sequential queue. The queued AddPolicyAgentRule goes out on the wire. For a workspace's first agent rule this command is especially slow because Auth also creates RuleBot and promotes it, so the request is often still in flight when the user reaches Troubleshoot and taps Clear cache on the same screen.

3. Clear cache runs clearOnyxAndResetApp, which today immediately rolls the in-flight request back into the persisted queue and snapshots that queue before clearing Onyx:

App/src/libs/actions/App.ts

Lines 900 to 949 in daa0474

	function clearOnyxAndResetApp(shouldNavigateToHomepage?: boolean) {
	// The value of isUsingImportedState will be lost once Onyx is cleared, so we need to store it
	const isStateImported = isUsingImportedState;
	rollbackOngoingRequest();
	const sequentialQueue = getAll();
	Navigation.clearPreloadedRoutes();
	// Seed LAST_FULL_RECONNECT_TIME so subscribeToFullReconnect doesn't fire a duplicate
	// ReconnectApp once the openApp() below lands NVP_RECONNECT_APP_IF_FULL_RECONNECT_BEFORE.
	const resetPromise = clearWorkboxRecoveryCaches().then(() =>
	clearOnyxAndSeedFullReconnect(KEYS_TO_PRESERVE)
	.then(() => {
	// Network key is preserved, so when exiting imported state, we should:
	// 1. Stop forcing offline mode so the app can reconnect
	// 2. Clear the IS_USING_IMPORTED_STATE flag
	// 3. Restore the original user session
	if (isStateImported) {
	setShouldForceOffline(false);
	Onyx.set(ONYXKEYS.IS_USING_IMPORTED_STATE, false);
	Log.info('[ImportedState] Exiting imported state mode, restoring original session');
	}
	if (shouldNavigateToHomepage) {
	Navigation.navigate(ROUTES.HOME);
	}
	if (preservedUserSession) {
	Onyx.set(ONYXKEYS.SESSION, preservedUserSession);
	Onyx.set(ONYXKEYS.PRESERVED_USER_SESSION, null);
	}
	if (preservedAccount) {
	Onyx.set(ONYXKEYS.ACCOUNT, preservedAccount);
	Onyx.set(ONYXKEYS.PRESERVED_ACCOUNT, null);
	}
	})
	.then(() => {
	// Requests in a sequential queue should be called even if the Onyx state is reset, so we do not lose any pending data.
	// However, the OpenApp request must be called before any other request in a queue to ensure data consistency.
	// To do that, sequential queue is cleared together with other keys, and then it's restored once the OpenApp request is resolved.
	// When exiting imported state, force openApp to run even though the variable might not be updated yet
	openApp(false, undefined, isStateImported).then(() => {
	if (!sequentialQueue || isStateImported) {
	return;
	}
	for (const request of sequentialQueue) {
	save(request);
	}
	});

4. rollbackOngoingRequest only moves the request in memory / on disk. It does not cancel the HTTP call that is already in flight:

App/src/libs/actions/PersistedRequests.ts

Lines 479 to 518 in daa0474

	function rollbackOngoingRequest() {
	Log.info('[PersistedRequests] rollbackOngoingRequest called', false, {
	hasOngoingRequest: !!ongoingRequest,
	ongoingCommand: ongoingRequest?.command ?? 'null',
	currentQueueLength: persistedRequests.length,
	});
	if (!ongoingRequest) {
	Log.info('[PersistedRequests] No ongoingRequest to rollback');
	return;
	}
	const requestToRollback = {...ongoingRequest, isRollback: true};
	Log.info('[PersistedRequests] Rolling back request to front of queue', false, {
	command: ongoingRequest.command,
	wasMarkedAsRollback: true,
	});
	// Prepend ongoingRequest to persistedRequests
	persistedRequests.unshift(requestToRollback);
	// Clear the ongoingRequest
	ongoingRequest = null;
	Log.info('[PersistedRequests] Rollback complete', false, {
	rolledBackCommand: requestToRollback.command,
	newQueueLength: persistedRequests.length,
	ongoingRequestCleared: true,
	});
	// Persist both changes to disk so a crash after rollback doesn't lose
	// the rolled-back request or leave a stale ongoingRequest on disk.
	trackOnyxWrite(
	Onyx.multiSet({
	[ONYXKEYS.PERSISTED_REQUESTS]: persistedRequests,
	[ONYXKEYS.PERSISTED_ONGOING_REQUESTS]: null,
	}),
	);
	}

So Auth still finishes the first transmission and creates the rule.

5. After Onyx is cleared, openApp reloads policy state from the server, including the newly created agent rule. Then the snapshotted queue is restored and the same AddPolicyAgentRule (same agentRuleID) is sent a second time.

6. Auth rejects the duplicate. HTTPS handling applies Auth onyxData first (which is where the "Auth AddPolicyAgentRule returned an error" string comes from), then the request's failureData (the generic Oops message):

App/src/libs/actions/OnyxUpdates.ts

Lines 41 to 69 in daa0474

	// First apply any onyx data updates that are being sent back from the API. We wait for this to complete and then
	// apply successData or failureData. This ensures that we do not update any pending, loading, or other UI states contained
	// in successData/failureData until after the component has received and API data.
	const onyxDataUpdatePromise = response.onyxData ? updateHandler(response.onyxData) : Promise.resolve();
	return onyxDataUpdatePromise
	.then(() => {
	// Handle the request's success/failure data (client-side data)
	if (response.jsonCode === 200 && request.successData) {
	return updateHandler(request.successData);
	}
	if (response.jsonCode !== 200 && request.failureData) {
	// 460 jsonCode in Expensify world means "admin required".
	// Typically, this would only happen if a user attempts an API command that requires policy admin access when they aren't an admin.
	// In this case, we don't want to apply failureData because it will likely result in a RedBrickRoad error on a policy field which is not accessible.
	// Meaning that there's a red dot you can't dismiss.
	if (response.jsonCode === 460) {
	Log.info('[OnyxUpdateManager] Received 460 status code, not applying failure data');
	return Promise.resolve();
	}
	trackExpenseApiError({
	command: request.command,
	jsonCode: response.jsonCode ?? 0,
	message: response.message,
	requestData: request.data,
	});
	return updateHandler(request.failureData);

7. AgentRulesList passes rule.errors straight into OfflineWithFeedback, so both messages appear under a rule that OpenApp already loaded as real server data:

App/src/components/AgentRules/AgentRulesList.tsx

Lines 49 to 55 in daa0474

	<OfflineWithFeedback
	key={rule.ruleID}
	pendingAction={rule.pendingAction}
	errors={rule.errors}
	errorRowStyles={styles.agentRulesErrorRow}
	onClose={() => clearPolicyAgentRuleErrors(policyID, rule.ruleID, rule)}
	>

Why the online-only path is fine

If the user saves while online, AddPolicyAgentRule completes and is removed from the queue via the sequential queue success path before Clear cache runs:

App/src/libs/Network/SequentialQueue.ts

Lines 199 to 218 in daa0474

	Log.info('[SequentialQueue] Removing persisted request because it was processed successfully.', false, {
	command: requestToProcess.command,
	remainingRequests: getAllPersistedRequests().length,
	});
	endPersistedRequestAndRemoveFromQueue(requestToProcess);
	// Only commit queueFlushedData (e.g. HAS_LOADED_APP: true) on success — HttpUtils resolves (not rejects) app-level
	// failures, so committing on a failed-but-resolved OpenApp/ReconnectApp would wrongly mark the app as loaded and
	// break self-healing on the next boot.
	if (requestToProcess.queueFlushedData && response?.jsonCode === CONST.JSON_CODE.SUCCESS) {
	Log.info('[SequentialQueue] Will store queueFlushedData.', false, {
	command: requestToProcess.command,
	queueFlushedDataLength: requestToProcess.queueFlushedData.length,
	});
	saveQueueFlushedData(...requestToProcess.queueFlushedData);
	}
	sequentialQueueRequestThrottle.clear();
	Log.info('[SequentialQueue] Continuing to process next request');
	return process();

The clear-cache snapshot then has nothing to replay for that create, so OpenApp alone restores a clean rule with no errors.

What changes do you think we should make in order to solve the problem?

We should fix the race inside clearOnyxAndResetApp so we only snapshot requests that have not already been applied by Auth. Use the existing sequential queue APIs (pause, getCurrentRequest, unpause) rather than agent-rule-specific filtering.

1. At the start of clearOnyxAndResetApp, pause the sequential queue so no additional write can start while reset is running:

App/src/libs/actions/App.ts

Lines 900 to 904 in daa0474

	function clearOnyxAndResetApp(shouldNavigateToHomepage?: boolean) {
	// The value of isUsingImportedState will be lost once Onyx is cleared, so we need to store it
	const isStateImported = isUsingImportedState;
	rollbackOngoingRequest();
	const sequentialQueue = getAll();

App/src/libs/Network/SequentialQueue.ts

Lines 82 to 90 in daa0474

	function pause() {
	if (isQueuePaused) {
	Log.info('[SequentialQueue] Queue already paused');
	return;
	}
	Log.info('[SequentialQueue] Pausing the queue');
	isQueuePaused = true;
	}

2. Await getCurrentRequest() so the single in-flight write settles before we snapshot. On success the queue already removes it, so it will not be restored after OpenApp. On a retriable failure the queue's own rollback puts it back into persisted requests, so it remains in the snapshot and is still preserved. If the await rejects, log and continue with reset rather than aborting Clear cache:

App/src/libs/Network/SequentialQueue.ts

Lines 643 to 648 in daa0474

	function getCurrentRequest(): Promise<void> {
	if (currentRequestPromise === null) {
	return Promise.resolve();
	}
	return currentRequestPromise;
	}

App/src/libs/Network/SequentialQueue.ts

Lines 199 to 218 in daa0474

	Log.info('[SequentialQueue] Removing persisted request because it was processed successfully.', false, {
	command: requestToProcess.command,
	remainingRequests: getAllPersistedRequests().length,
	});
	endPersistedRequestAndRemoveFromQueue(requestToProcess);
	// Only commit queueFlushedData (e.g. HAS_LOADED_APP: true) on success — HttpUtils resolves (not rejects) app-level
	// failures, so committing on a failed-but-resolved OpenApp/ReconnectApp would wrongly mark the app as loaded and
	// break self-healing on the next boot.
	if (requestToProcess.queueFlushedData && response?.jsonCode === CONST.JSON_CODE.SUCCESS) {
	Log.info('[SequentialQueue] Will store queueFlushedData.', false, {
	command: requestToProcess.command,
	queueFlushedDataLength: requestToProcess.queueFlushedData.length,
	});
	saveQueueFlushedData(...requestToProcess.queueFlushedData);
	}
	sequentialQueueRequestThrottle.clear();
	Log.info('[SequentialQueue] Continuing to process next request');
	return process();

3. Only after that settle, call rollbackOngoingRequest() and then getAll() for the snapshot. Keeping rollback after settle is intentional: it preserves orphaned ongoing requests that were moved to ongoing without an active sequential-queue currentRequestPromise (the case covered by the existing AppTest). Removing rollback entirely would regress that preservation path:

App/src/libs/actions/PersistedRequests.ts

Lines 479 to 518 in daa0474

	function rollbackOngoingRequest() {
	Log.info('[PersistedRequests] rollbackOngoingRequest called', false, {
	hasOngoingRequest: !!ongoingRequest,
	ongoingCommand: ongoingRequest?.command ?? 'null',
	currentQueueLength: persistedRequests.length,
	});
	if (!ongoingRequest) {
	Log.info('[PersistedRequests] No ongoingRequest to rollback');
	return;
	}
	const requestToRollback = {...ongoingRequest, isRollback: true};
	Log.info('[PersistedRequests] Rolling back request to front of queue', false, {
	command: ongoingRequest.command,
	wasMarkedAsRollback: true,
	});
	// Prepend ongoingRequest to persistedRequests
	persistedRequests.unshift(requestToRollback);
	// Clear the ongoingRequest
	ongoingRequest = null;
	Log.info('[PersistedRequests] Rollback complete', false, {
	rolledBackCommand: requestToRollback.command,
	newQueueLength: persistedRequests.length,
	ongoingRequestCleared: true,
	});
	// Persist both changes to disk so a crash after rollback doesn't lose
	// the rolled-back request or leave a stale ongoingRequest on disk.
	trackOnyxWrite(
	Onyx.multiSet({
	[ONYXKEYS.PERSISTED_REQUESTS]: persistedRequests,
	[ONYXKEYS.PERSISTED_ONGOING_REQUESTS]: null,
	}),
	);
	}

App/tests/actions/AppTest.ts

Lines 113 to 147 in daa0474

	test('clearOnyxAndResetApp preserves rolled-back ongoing requests across reset', async () => {
	const persistedRequest: Request<'reportMetadata_1' | 'reportMetadata_2'> = {
	command: 'AddComment',
	successData: [{key: 'reportMetadata_1', onyxMethod: 'merge', value: {}}],
	failureData: [{key: 'reportMetadata_2', onyxMethod: 'merge', value: {}}],
	requestIndex: 123,
	};
	jest.spyOn(Navigation, 'clearPreloadedRoutes').mockImplementation(() => {});
	await Onyx.set(ONYXKEYS.NETWORK, {shouldForceOffline: true});
	await PersistedRequests.save(persistedRequest);
	await waitForBatchedUpdates();
	PersistedRequests.processNextRequest();
	await waitForBatchedUpdates();
	expect(PersistedRequests.getOngoingRequest()).toEqual(persistedRequest);
	await App.clearOnyxAndResetApp();
	await waitForBatchedUpdates();
	await waitFor(async () => {
	const diskQueue = (await getOnyxValue(ONYXKEYS.PERSISTED_REQUESTS)) ?? [];
	expect(diskQueue).toEqual(
	expect.arrayContaining([
	expect.objectContaining({
	command: 'AddComment',
	requestIndex: 123,
	isRollback: true,
	}),
	]),
	);
	expect((await getOnyxValue(ONYXKEYS.PERSISTED_ONGOING_REQUESTS)) == null).toBe(true);
	});
	});

4. After clearOnyxAndSeedFullReconnect empties the persisted queue keys, unpause the sequential queue before calling openApp. openApp itself is enqueued as a sequential write, so leaving the queue paused here hangs the reset. If anything in the reset promise rejects after pause(), unpause in a failure catch so Clear cache never leaves the app stuck with a paused queue:

App/src/libs/actions/App.ts

Lines 936 to 949 in daa0474

	.then(() => {
	// Requests in a sequential queue should be called even if the Onyx state is reset, so we do not lose any pending data.
	// However, the OpenApp request must be called before any other request in a queue to ensure data consistency.
	// To do that, sequential queue is cleared together with other keys, and then it's restored once the OpenApp request is resolved.
	// When exiting imported state, force openApp to run even though the variable might not be updated yet
	openApp(false, undefined, isStateImported).then(() => {
	if (!sequentialQueue || isStateImported) {
	return;
	}
	for (const request of sequentialQueue) {
	save(request);
	}
	});

App/src/libs/Network/SequentialQueue.ts

Lines 457 to 488 in daa0474

	function unpause() {
	if (!isQueuePaused) {
	Log.info('[SequentialQueue] Unable to unpause queue. We are already processing.');
	return;
	}
	const currentPersistedRequests = getAllPersistedRequests();
	const currentOngoingRequest = getPersistedOngoingRequest();
	const numberOfPersistedRequests = currentPersistedRequests.length;
	const persistedCommands = getCommands(currentPersistedRequests);
	Log.info('[SequentialQueue] Unpausing the queue', false, {
	numberOfPersistedRequests,
	hasOngoingRequest: !!currentOngoingRequest,
	persistedCommands,
	});
	isQueuePaused = false;
	// If there are no persisted requests, we need to flush the Onyx updates queue
	if (numberOfPersistedRequests === 0 && !currentOngoingRequest) {
	Log.info('[SequentialQueue] No persisted requests, flushing Onyx updates queue');
	flushOnyxUpdatesQueue();
	}
	// We pass shouldResetPromise=false to preserve the existing isReadyPromise so that
	// pending READ requests (waiting via waitForIdle()) resolve correctly after WRITEs complete.
	Log.info('[SequentialQueue] Calling flush(false) to start processing', false, {
	numberOfPersistedRequests,
	});
	flush(false);
	}

5. Keep the existing restore loop after openApp resolves. Requests that never reached the server stay in the snapshot and are re-saved. Requests that completed while we waited are absent, so they are not double-sent.

What alternative solutions did you explore? (Optional)

Reminder: Please use plain English, be brief and avoid jargon. Feel free to use images, charts or pseudo-code if necessary. Do not post large multi-line diffs or write walls of text. Do not create PRs unless you have been hired for this job.