CPF2817: Copy command ended because of error

What it means

CPF2817 is an escape message from QCPFMSG with the text "Copy command ended because of error". CPYF sends it, along with other IBM i copy commands, as the final word when a copy fails. The copy command first logs one or more diagnostic messages that describe the actual problem, then ends with CPF2817.

So CPF2817 on its own tells you almost nothing. The message to read is the one just above it in the job log. That can be anything from a missing file to a format mismatch, a lock, or bad data in a record.

One common case surprises people. When the from-member is empty, CPYF logs a message that the empty member wasn't copied, and then ends with CPF2817. Programs that copy daily files that may be empty must allow for this. With MBROPT(*REPLACE), the to-member keeps its old records in that case, because nothing was copied over it.

Common causes

• The from-member is empty, so there was nothing to copy.
• The from-file, to-file or a member doesn't exist, or the to-file is missing and CRTFILE(*YES) wasn't specified.
• The record formats of the two files differ and the command didn't say how to handle that with FMTOPT, for example *MAP and *DROP, or *NOCHK.
• Another job has the to-file or member locked, or the user lacks authority to one of the files.
• Records failed during the copy, such as duplicate keys in a unique to-file or data that doesn't fit the to-file's fields, and the number of errors went over the ERRLVL limit.
• A parameter combination isn't allowed, for example TOMBR(*FROMMBR) in a case where it can't be used.

How to find the problem

1. Open the job log with DSPJOBLOG, or press F10 on the message screen to show detailed messages. The diagnostic messages just above CPF2817 give the reason.
2. Put the cursor on each of those messages and press F1 for the full text, which names the file, member or record involved.
3. Check the files with DSPFD and their record formats with DSPFFD if a format mismatch is suspected.
4. If a lock is the reason, run WRKOBJLCK on the to-file to see which job holds it.

How to fix it

• Fix the problem the earlier diagnostic message names, then rerun the copy.
• For files that may be empty, decide what an empty file means. A common CL pattern clears the to-member when CPYF fails on an empty from-member. Only do that if an empty file is a valid state, because an empty master file may mean someone cleared it by mistake.
• Use FMTOPT(*MAP *DROP) when the files have different layouts with matching field names, or FMTOPT(*NOCHK) when you really want a byte-for-byte copy.
• Add CRTFILE(*YES) when the to-file may not exist yet.
• Avoid a blanket MONMSG MSGID(CPF2817) with no action. It hides every kind of copy failure, not only the one you expected.

What it looks like

Copy command ended because of error.

DSPMSGD MSGID(CPF2817) MSGF(QSYS/QCPFMSG)

Technical reviewer: Albert Joseph, WND Software.

Last reviewed 2026-10-18 by the WND Software team. Written in our own words. For the full reference, check IBM’s documentation for your IBM i release.